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:

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

BP Dev Chat Summary, September 4

5.0.0’s schedule

  1. Second beta release: September 10.
  2. First release candidate: ~ September 16.
  3. 5.0.0 release: ~ September 30.

Issues & Feedbacks about the first beta release

Some i18n issues appeared into the BP REST API code and have since been fixed by @espellcaste. @im4th will improve the bp.apiRequest JavaScript function before beta2 (#8131).

IAmTheWebb reported that he hasn’t noticed any regression issues but also informed us he hasn’t found the time to test the new features yet. The lack of ticket report is a bit worrying as it makes us wonder if the beta1 has actually been tested by BuddyPress plugin or theme developers 🤔.

@boonebgorges explained it wasn’t easy to test the BP REST API as it required building clients. Having the BP REST API documentation site available would probably help.

The BP REST API documentation site

@johnjamesjacoby & @netweb have been working on the developer.wordpress.org needed set-up to host the BP REST API documentation site. Although we are very confident they will soon fix #4601-meta, we decided to wait until September 20 before applying our backup plan.

In case we can’t make it on developer.wordpress.org @im4th will buy a specific domain name for the staging site we used to write the documentation and we’ll make this site widely available.

BuddyPress plugin & theme developers will be able to consult The BP REST API documentation before the 5.0.0 release 💯.

Hello BuddyPress modal

BuddyPress 3.0.0 introduced this modal to replace the Welcome Screen. We use it to inform about the new features introduced in the new major releases of BuddyPress.

@im4th shared a patch on #8132 to make this modal more inline with the WordPress Administration styles. @johnjamesjacoby shared his thoughts about it on the ticket and agreed during dev-chat that matching core’s modal would be best.

@im4th is 🇫🇷 so there are probably some english mistakes in the text parts of the patch. BuddyPress contributors : don’t hesitate to find and fix them 🙏

5.0.0-beta2

We decided to package a second beta next week to remind our contributors we need their help to test our contributions. Let’s not wait for the stable release to find bugs we could have avoided during the beta period!

Next dev-chat

It will happen on September 18th at 19:00 UTC in #BuddyPress slack channel, just before the release candidate.

PS: @dcavins couldn’t attend to the dev-chat but recently shared in our Slack channel he will soon publish an overview about the changes introduced by the BP Invitations API 👌.

#5-0-0

BuddyPress 5.0.0-beta1

Hi !

We’ve just published the 1st beta version of our next major release. You can read more about it here: https://buddypress.org/2019/08/buddypress-5-0-0-beta1/

👩🏻‍💻👨🏽‍💻

#5-0-0

BP Dev Chat Summary, August 21

5.0.0’s schedule

Here are three important dates about our next major version:

  1. First beta release: August 28.
  2. First release candidate: ~ September 16.
  3. 5.0.0 release: ~ September 30.

BP Invitations API

@dcavins has committed this new API to manage Invitations/Membership Requests across components. The first BP Component to enjoy it is naturally the Groups one. Many thanks and huge congratulations for the accomplished work 👏🤝. See #6210 for more details about it.

BP REST API

Code improvements

  • He also adapted the Group Invites and the Group Membership Requests endpoints so that they are now using the BP Invitations API.
  • The create_item() method of the Group Membership controller is now taking in charge the action to let members join a public group.
  • WP_REST_Server::DELETABLE methods are now all returning an object with two keys. The first one informs about the success of the DELETE request and the second one contains the previous BP object as it existed before its deletion.

Documentation

The content is almost ready! Documenting the Group Invites and the Group Membership Requests endpoints (the last ones) will be achieved before the beta release.

Making it available from BuddyPress.org is in very good hands @johnjamesjacoby will work on it asap to try to have it ready around beta release so that it should be easier for contributors to play with the BP REST API during our Beta/RC release steps.

How the BP REST API will be included into BuddyPress Core for this beta release?

To keep working from our BP REST GitHub repository to fix potential bugs / improvements, we will include it during our build process a bit like what happens today with BP CLI: see this comment on #7156 for more details.

This means:

  • the BP REST API plugin, if active, will take over BuddyPress, making it easier to carry on maintaining it from GitHub during the Beta/RC time.
  • If contributors are using trunk to beta test, they’ll need to npm install & grunt build to get the BP REST API into this build.

5.0.0 milestone’s remaining tickets

  • #8046 & 8093 have been moved to next release.
  • #8103 (BP Legacy Companion Stylesheet for Twenty Nineteen) is kept during the beta/RC to leave a last opportunity to include it before final release if it gets some contributions/testing.
  • #8123 will be committed asap & before beta release.

Beta Release tasks

  • @im4th will take in charge the beta release packaging
  • @dcavins will try to post on this blog to introduce the BP Invitations API
  • We still need to write the announcement post for BuddyPress.org. A draft for it is available on BuddyPress.org (the title is BuddyPress 5.0.0-beta1), don’t hesitate to add the information you think are important to mention. I’ll polish the writing part 🖼 📝

Next dev-chat

It will happen on September 4th at 19:00 UTC in #BuddyPress slack channel. Of course is something goes wrong with right after the beta release, we’ll always be able to meet next week.

#5-0-0

BP Dev Chat Summary: August 7, 2019

5.0.0’s schedule

At the end of our discussions, considering the work we still have to achieve to feel satisfied about ourselves, we’ve decided to postpone the first beta release to the last week of August. Our new targeted date for 5.0.0-beta 1 is August 28. Thanks for everyone’s comprehension 🙏

BP REST API focus

NB: we didn’t have enough time to decide about “how to include the BP REST API into BuddyPress Core“. We will do it during our next dev chat. In the meantime, you’re welcome to contribute to #7156.

Documentation

We’re making great progress on this topic. More than 50% of our endpoints are now documented. @im4th shared the link of the testing site we use waiting for #4601 to be fixed (@im4th and @espellcaste are 🤞).

Writing this documentation is also very helpful to improve the API code: 10 pull requests were generated and merged so far.

@im4th is 💯 confident all the endpoints introduced into version 5.0.0 of BuddyPress will be documented before its public release.

Code improvements

In addition to these PRs @dcavins has been working hard on adapting the Group Invites and the Group Request Membership endpoints to the new BP Invitations API. @espellcaste & @im4th ‘s reviews of his patches led to 2 important conversations during the dev chat.

What endpoint should handle the action “a user joins a group”?

While @boonebgorges intuitively expects a POST request to the Group Membership endpoint to succeed if the group is public, I was wondering if “joining a public group” could be interpreted as “requesting an already accepted membership request” and as such use the Group Request Membership endpoint instead. @dcavins informed the second option would generate a consistency issue as the response object wouldn’t fit with “joining a public group“. We decided to use the first option (See PR209).

How should we build the response object to the WP_REST_Server::DELETABLE methods?

So far we were returning the object as it existed before its deletion for all endpoints excepting for the Members endpoint. The Members controller is actually extending the WordPress Users one : so we decided to follow WordPress way of building the response object in this case. See PR210.

BP Invitations API

See #6210 for more details about the API. @im4th & @dcavins are confident about committing the changes into BuddyPress Core to make the API available to everyone for 5.0.0 🙌. A Back compatibility mechanism is in place and our testing did great. The soonest the patch will be converted, the best it will be to finish the needed adaptations of the BP REST API (See PR206). @dcavins will work asap 💪 on the committing task, making sure to split the patch into small & consistent chunks.

5.0.0 milestone’s tickets

As we were already playing overtimes for 30 minutes for this dev chat, we will decide about whether to move the remaining tickets to a next/future release or not during our next dev chat.

If you have CSS skills, you are very welcome to contribute on #8103. If you’re not familiar with working with Trac patches, we’ve put together this Twenty Nineteen child theme to make things easier for you.

Next dev-chat

It will happen on August 21th at 19:00 UTC in #BuddyPress slack channel. As @im4th said at the end of this dev-chat:

Let’s meet again in 2 weeks with everything ready for a beta release the week after 💪 🙌

#5-0-0

A category to store your BuddyPress blocks

Dear BuddyPress block developers,

We thought about you! As the BP REST API will be included into our next major release (5.0.0), it will open up new opportunities to create great features and of course BuddyPress blocks. To make things obvious for our end users, what about storing them into the BuddyPress blocks category we’ve just added to BuddyPress Core (See changeset #12418) ?

Screenshot of the Block selector

To do so, when registering your block type, you’ll just need to set the category property of your block to buddypress. Here’s an example below.

( function( blocks, element ) {
    var el = element.createElement;

    blocks.registerBlockType( 'bpeb/example-block', {
        title: 'BuddyPress example block',
        description: 'A BuddyPress example block to show how to be listed into the BuddyPress blocks category.',
        icon: 'buddicons-groups',
        category: 'buddypress',
        edit: function() {
            return el(
                'p',
                {},
                'BuddyPress blocks are stored into the BuddyPress blocks category.'
            );
        },
        save: function() {
            return el(
                'p',
                {},
                'BuddyPress blocks are stored into the BuddyPress blocks category.'
            );
        },
    } );
}(
    window.wp.blocks,
    window.wp.element
) );

Get the BuddyPress Example Block from Gist.GitHub | Block Editor Handbook

NB: This category will be available as soon as 5.0.0 will be released.

😉 👋

#5-0-0

BP Dev Chat Agenda: July 24, 2019

This is the agenda for our next Dev Chat which will happen on July 24th at 19:00 UTC (tomorrow 😱):

  • Feedbacks about latest BuddyPress 4.4.0 upgrade.
  • Updates about 5.0.0 tickets. In particular patch testing of #8013, #8026, #8079 & #8103.
  • Updates about the latest BP REST API improvements.
  • BP REST API documentation site.

This meeting is held in the #BuddyPress channel of the Making WordPress Slack.

If you have anything you wish to add to this agenda or specific items related to those listed above, please leave a comment below.