Updates about the Tickets into the 5.0.0 milestone
#8045 is achieved: we now have our very first core feature using the BP REST API. If you chose to use BP Nouveau as your template pack (it is the default template pack for new installs), your group administrators will enjoy a brand new interface to manage the members of their group(s).
The interface is more dynamic than our legacy one and Administrators of popular groups will probably love the search feature! Finding the specific member they want to promote, demote, ban or remove is faster than ever!
#6210@dcavins is working on a new version of the patch to adapt it to play nicer with BP Nouveau & see how things will evolve with the BP REST API. He worked very hard 💪 🏋🏻♂️ so far and I believe he’s very close to achieve his goal. I think it’s a very promising feature that will first improve how we handle group invitations and soon give new opportunities for other objects such as sites of a network. I also think it’s an interesting way to test & review the group invites & requests BP REST API endpoints.
There are 7 tickets with patches. Feel free to help us: testing patches and confirming they do the job is a already a great help. If you can improve them: it’s even greater! If you don’t know where to start, read this comment about how to test BuddyPress patches.
We still have work on this “field” 😅 I’ve submitted a pull request that is implementing them for a bunch of endpoints. @espellcaste: please have a look at it soon and commit if you feel like me & @boonebgorges the approach is good.
The xProfile REST fields will need an extra work as the meta table is a bit different: we can attach a meta to a data, a field or a group of fields. I’ve posted an issue about it with a suggestion to handle this specific case. I’ll update it with a new pull request to adapt the one I was talking about into the previous paragraph.
The current endpoint about Threads/Private messages is more sensitive imho. REST fiels are messages metadata not threads ones. FYI, I’ve been also exploring how to use the BP REST API into the BP Nouveau Messages UI. I think I will carry on because it’s a nice way to eventually improve it.
I think we need to harmonise their use, for instance in BP REST Activity, BP REST Groups, BP REST Members, the links should all include a filter to let plugins add custom ones if needed. There should be links for the Private Message object to transport the “star” link, and probably the links of the users involved into the message…
During our latest dev-chat, we’ve been talking about putting together a documentation site for the BP REST API. I’ve been exploring the subject more deeply this week and I believe we should take this opportunity to try to ship a first version of the developer resources site.
I think 5.0.0 is an interesting time/release (as it’s a very developer oriented one with the inclusion of the BP REST API) to start powering BuddyPress developers with some resources just like WordPress does with its DevHub project.
The « BP » DevHub project?
@tw2113 started working on a BuddyPress Code Reference site 3 years ago, see #6812. In his last comment he expressed his concern about the lack of developer content the site would offer. Then I thought the BP REST API documentation could be a great companion to this BuddyPress Code Reference! So I’ve carried on his work and built a local test site to check how difficult it could be to make this real.
It’s doable before the 5.0.0 release!
It took me a couple of days, following and adapting the installation steps described in this chapter of the WordPress Documentation handbook, to build a « proof of concept » framework. Actually all I had to do was to create a child theme for the « wporg-developer » theme and share 2 patches on the Meta Trac (see #4516 & #4517) so that the Meta Team could fix the 2 issues I’ve found during my explorations.
Install/Build the latest version of BuddyPress 😍 (no need to activate it).
Run the WP CLI command using the BuddyPress directory of point 5 as the argument. For example: wp parser create path/to/wp-content/plugins/buddypress --user=1 or wp parser create path/to/wp-content/plugins/buddypress/build --user=1 if trunk is used.
Install & activate the Handbook plugin (We don’t need the wporg-markdown & wporg-cli plugins as we don’t write our documentation on GitHub and moreover it would import the WordPress REST API and Coding standards documentations).
Install & activate the « bporg-developer » child theme I’ve built using the Customizer live preview (so that it automatically creates the starter content – make sure the fresh_site option has its value set to 1).
Go to the General Settings Administration screen and insert the version of BuddyPress into the BuddyPress latest stable version option.
Wait, but what about the BP REST API Documentation?
If you’d go on the BP REST API Handbook at this stage you wouldn’t see any content. We need to create it. We chose to have it generated thanks to the REST schemas of our REST endpoints. The Restsplain plugin does this task for all the WordPress and custom endpoints of the website.
Using it as it would first mean to activate BuddyPress (and possibly the BP REST plugin if not yet included into BuddyPress).
There are benefits of having the generated documentation this way as new endpoints would automatically be included. It’s also possible to create and attached content to our endpoints using the post type included inside the plugin. But there are also disadvantages:
All BuddyPress components would need to be activated.
The React Application inside the Restsplain plugin is displaying the real URLs at various places.
It is also including a feature to use them into a specific container to make real REST requests.
The good new is: we can filter the list of endpoints the Restsplain plugin is generating. So I’ve added this filter to the bporg-developer theme and the documentation generation is now restricted to BuddyPress endpoints. Then I thought we could avoid the need for BuddyPress to be activated by first looking for an external Json file (a static copy of the array expected by Restsplain, where links are « anonamisized »).
But still, I had to remove completely the live testing of endpoints feature. Although it can be done in CSS, I chose to edit the plugin because:
it has not been updated for 7 months and as a result contains outdated node modules and React library.
Some real links are built in React using the rest base URL.
One of the link of the React endpoint viewes is triggering the live testing.
As a result the version of the plugin I suggest to use is the fork I’ve made here. As I’ve edited the React part, I also edited the styles to match the BuddyPress.org colors. Here’s how it looks:
As you can see it’s very different from the output made by the WordPress handbook plugin. The best I could do to make it more looking like it was to use the [restsplain] shortcode in a page.
That’s why I think we should probably only use this plugin to write a static version into the BP REST API handbook post type of what it generates dynamically.
We have 14 endpoints to document for 5.0.0 and 8 others for the 6.0.0 release and I think we can do some copy/pasting: it won’t take too much time and the layout of the documentation will be the same for every potential handbooks (eg: BuddyPress plugins or themes).
Moreover we’ll be able to improve the navigation grouping endpoints by components, we’ll be able to use more meaningful titles for the GET, POST, PATCH, DELETE methods, eg: Get a specific user, add a user, update a user and remove a user. Finally we would be able to use code examples using our bp.apiRequest function instead of the fetch function Restsplain uses. Below is a screenshot showing what I mean about this copy/pasting task.
What if we’re running out of time building the developer resources site?
It would be too bad, but not a so much big deal! I’ve already created a documentation site for the BP REST API. You can test it here. We would simply need to attach to this site a more meaningful domain name 😉
As a reminder, it will happen this Wednesday (June 26) at 19:00 UTC into our Slack channel: #BuddyPress. All BuddyPress Contributors are very welcome to join us. If you’re a bit intimidated (you shouldn’t!) but still want to give us your opinion about this topic, please use the comments area below 👍
A huge work has been accomplished by @espellcaste 💪 so far from the feature as a plugin “BP REST” and we think the 5.0.0 release will be a good time to bring the REST API within BuddyPress core. As explained in #7156 it will introduce 14 BuddyPress endpoints and you’ll soon be able to play with activity updates, groups, members, private messages and extended profile fields using REST requests 🙌
8 other endpoints (eg: blogs, friends) will arrive in 6.0.0.
BP REST Documentation
As @boonebgorges said during the chat, this part is very important for us to help you build great BuddyPress plugins thanks to this new API. We’ve been looking for a nice tool to generate this documentation out of the endpoints schemas and we think we’ve found a good solution to start. We now have to put up a website to host this documentation. I’ll take care of sketching out the next steps of this site and @boonebgorges will be able to help for the domain name.
Let’s start using the API within BuddyPress core!
The best way to help you discover the BP REST API potential is to use it ourselves 😉. We plan to do so by improving how Group members are managed within the Group Manage screen (front-end) and the Group Admin screen (back-end). Below is a video demo to let you discover a bit early how it should look like on the front-end of your community site.
You can follow our progress from the #8045 ticket.
How to include the BP REST API into the BuddyPress plugin package?
We’ve been discussing about it for about 30 mins during the chat and we haven’t decided yet how this will happen. We have 2 options:
Carry on maintaining it from GitHub.com and include it during the BuddyPress plugin’s build process (that’s what we’re doing for BP Default & BP CLI)
Merge it into BuddyPress Core.
There are “pros” and “cons” for both options. For example, maintaining it from GitHub can be confusing for contributors because it adds a second place to report for this part of BuddyPress as @boonebgorges noted. It’s also problematic regarding the history of how the decisions were made: it would be “tied up in two places“. @espellcaste also expressed his preference, despite the fact working in GitHub is more convenient, about keeping things “in house” (we have less control about the future of GitHub). Finally @boonebgorges also explained we could keep it on GitHub for a couple of releases before bringing it home as “once we go Trac, we cannot go Back“.
Another relative point on this subjet: how plugins should behave if they are both activated?
Should the plugin BP REST take over BuddyPress ? Meaning all endpoints can be maintained from the GitHub repository.
Should it be BuddyPress? Meaning the BP REST plugin would only be used to develop the 8 remaining endpoints.
We agreed we still have time until the first beta release to decide, but if you have ideas or recommandations : please share them in comments 😊
About the 5.0.0 release schedule
We agreed on a first date : 5.0.0-beta1 will be released around August 15.
As discussed during the chat, it will give us the time to work on the documentation site and decide about the « BP REST API including » strategy.
It should also give us the time to clear the tickets list of the milestone, there are around 10 tickets left and you are very welcome to give us a hand testing or suggesting patches.
Until Beta1 we will have a dev chat every other Wednesday at 19:00 UTC in #BuddyPress. Here is the planning of our next meetings:
August 21 (probably dedicated to the results and 1st feedbacks about 5.0.0-beta1)
To be confirmed for the other dates.
If you are going to Berlin to attend to the WCEU 2019: have fun, make good connections and learn great things! @johnjamesjacoby will be there, don’t hesitate to enjoy his conference 👌 and chat with him about BuddyPress 😍
You can also decide to give a hand to BuddyPress during this WordCamp thanks to the contributing area! We’ll be very happy to help from where we are 😁
We chatted briefly about the current state of the API code https://github.com/buddypress/bp-rest. CRUD coverage for BP content types is about 90% complete, with a few pending PRs. Renato and Boone are working toward 100% in the next week or two.
There was general agreement that the BP 5.0 release should focus on the REST API, with a tentative date of Q1 2019 suggested. A few discussion points:
Questions about API usage have already come in at a fairly fast pace on the GitHub issue tracker. As such, we aim toward having documentation covering basic usage by the time we ship. For reference, the WP REST API documentation on developer.wordpress.org contains both hand-built documentation and automatically generated docs. See https://developer.wordpress.org/rest-api/ and https://developer.wordpress.org/rest-api/reference/. We’re hopeful that we can leverage some of wordpress.org’s tools for automated generation of documentation, or perhaps a third-party tool like https://github.com/humanmade/Restsplain In the upcoming weeks, we’ll try to collect team wisdom on the current state of buddypress.org and the options available to us.
If it’s not possible to make major mods to our wordpress.org documentation in order to support these automatically-generated docs, we might roll our own outside of wordpress.org, much in the manner of https://wp-api.org prior to the core REST API merge.
Authentication is likely to be a point where documentation is especially important, particularly because the majority of BP site users are authenticated. There have also been some questions on the GitHub repo about the consistency of making authenticated requests, the use of nonces, etc. For reference, here’s the core page on API authentication: https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/
BP core API usage
There was general agreement that it’d be wise for BuddyPress itself to use the API in at least a handful of ways for the 5.0 release. In addition to enabling new, AJAX-powered interfaces, the process of building on top of the REST API for BP itself will help the team gain familiarity with the nature of the API, and improve its usability before the public launch.
In some cases, existing AJAX can be converted to use the API. See eg https://buddypress.trac.wordpress.org/ticket/8043#ticket. In other cases, we may consider adding new interface features using the API. See eg https://buddypress.trac.wordpress.org/ticket/8045#ticket. While it’s generally safest to modify existing functionality in the Dashboard – where our interfaces aren’t easily customizable by themes etc – it may be possible to swap out some front-end stuff (say, in Nouveau) without too much breakage. My initial thought was directory AJAX, but then I remembered that some of those existing endpoints return markup rather than JSON-formatted entities. Any ideas are welcome.
In support of the 5.0 push, we’d like to reestablish regular project meetings. The current proposal is to use the old meeting time of Wednesdays at 19:00 UTC, every other week beginning February 13.
We’ll be having an informal chat in the #buddypress Slack channel at 15:00 UTC on Monday, January 28 to talk about BuddyPress 5.0, and especially next steps for the BP REST API project https://github.com/buddypress/bp-rest. This will likely lead into some broader discussion about BP focuses for 2019. I’ll post an update here afterward for those who are interested but unable to attend.
BuddyPress 5.0.0 will require WordPress 4.7 or greater. See https://buddypress.trac.wordpress.org/ticket/8025, as well as the perennially ripping read, https://codex.buddypress.org/getting-started/wordpress-version-compatibility/.