bp.apiRequest(), your JavaScript Buddy to help you start using the BP REST API

In BuddyPress 5.0.0 (Release date ~ September 30, 2019), we’re introducing the BP REST API: a new way for BuddyPress developers to interact with the components of BuddyPress powered community sites.

If you’re familiar with the WordPress REST API, you should easily find out how to use the BP REST API as it extends it to provide new community oriented endpoints.

The BP REST API, just like the WP REST API, uses a cookie authentication. You need 4 things to get a response from one of the BP REST API endpoints :

1. The rest_nonce
2. The WP REST root URL rest_url()
3. One of the available BuddyPress endpoint’s path, for example /buddypress/v1/members
4. The transport method (GET, POST, PUT, DELETE, OPTIONS).

You can build everything yourself into your JS script making sure to carry points 1. & 2. from PHP using the wp_localize_script() function.

You can also add a dependency to bp-api-request when enqueueing your JS script to :

• save some time ⏱
• make sure it will work for all the WordPress versions BuddyPress supports (4.7 to latest) 😅

Adding a dependency to bp-api-request

wp_register_script(
    'your-plugin-js-handle', // The handle to use when enqueueing your script.
    'https://site.url/wp-content/plugins/your-plugin/js/your-JavaScript-file.js',
    array(
        'bp-api-request', // The dependency to add to use the bp.apiRequest function.
    ),
    '1.2.3', // Your plugin version.
    true     // True to load your script into the footer. False otherwise.
);

Doing so, you’ll just need to enqueue your JavaScript file at the right time and for the right context using wp_enqueue_script( 'your-plugin-js-handle' ) without having to care about the REST nonce and the WP REST root URL.

function your_plugin_enqueue_assets() {
    // Only loads the JavaScript when a user is viewing his profile.
    if ( bp_is_my_profile() ) {
        wp_enqueue_script( 'your-plugin-js-handle' );
    }
}
add_action( 'bp_enqueue_scripts', 'your_plugin_enqueue_assets' );

Using bp.apiRequest() within your JS script

The only elements you’ll have to care about are:

• The BuddyPress endpoint’s path of your choice (path).
• The transport method (type).
• Specific arguments when needed (data).
• to download the 5.0.0-beta2 of BuddyPress to test 👍

You’ll need to group all these elements into an object looking like the highlighted lines below:

( function( bp, $ ) {
    window.bpRestApiResponse = {};

    var helloBPApiRequest = function() {
        bp.apiRequest( {
            path: '/buddypress/v1/members/me',
            type: 'GET',
            data: {
                context: 'view',
            }
        } ).done( function( data ) {
            bpRestApiResponse = data;
        } ).fail( function( error ) {
            alert( error.message );
        } );
    };
	
    $( document ).ready( helloBPApiRequest );
    
} )( window.bp || {}, jQuery );

From there, If you log the bpRestApiResponse variable into your browser’s console when visiting your BuddyPress profile you’ll see the JSON object the BP REST API should respond to you.

Oh.. wait but how can I get all BuddyPress endpoint paths etc. ?

We wrote a complete documentation with an example of use for each endpoint. We will soon make it available on the BuddyPress.org network.

In the meantime, if you’re eager to have some fun with the BP REST API, simply replace /buddypress/v1/members/me with /buddypress/v1 into the helloBPApiRequest()function of the above example.

Logging bpRestApiResponse will now give you all available endpoints, their corresponding transport methods and arguments for your community site (The ones of your active BuddyPress components) 😉

#5-0-0