Approaches for a complete sites endpoint and an expanded WP_Site_Query

Multisite office hours are held every Tuesday at 16:00 UTC in #core-multisite. The next will be Tuesday 16:00 UTC.

Creating a useful sites/ endpoint for the REST API and making WP_Site_Query more useful have been frequent topics over the last few weeks in #core-multisite. Quite a bit of discussion has been centered around the idea of a global wp_blogmeta table, whether it’s a good fit for core, and (if so) how to approach its introduction. See #37923 and the previous make/core post discussing a sites endpoint for additional background.

The intent of this post is to step back a bit and clarify the issues at hand to help identify the right solution(s).

The initial site information problem

A request to a global wp-json/wp/v2/sites/ endpoint on a network should return a set of site objects, similar to how wp-json/wp/v2/posts/ returns a set of post objects. A request to wp-json/wp/v2/sites/4 would return a single site object.

Written today each site object, represented as WP_Site in PHP, would provide at least this data:

  • ID
  • domain
  • path
  • registered
  • last_updated
  • public
  • archived
  • mature
  • spam
  • deleted
  • lang_id

The above fields all mirror what is available in the global wp_blogs database table installed with multisite. These are useful on their own, but additional data is frequently required.

Example: One piece of the admin that would be great to power with the REST API is the My Sites menu that multisite users see in the toolbar. To build this view, the home URL, admin URL, and site name are all necessary. In PHP, this data is made available through magic properties on the WP_Site object. When home, siteurl, blogname, or post_count is requested, the site uses switch_to_blog() and get_option() to populate the data from the individual site’s options table. If 25 sites are on the list, this generates 25 context switches and accesses 25 different tables.

There are at least a few approaches here:

  • Mirror the existing PHP experience and ensure properties are populated before the REST API response is returned. Possibly introduce a lighter weight switch_to_blog() option.
  • Provide a basic site object as well as an option to _embed other data in the response.
  • Migrate these properties into wp_blogs from wp_#_options as additional columns.
  • Migrate these properties into a global wp_blogmeta table.
  • Migrate these properties into another shared global space.

The querying sites problem

It’s currently possible to query for sites by the default fields listed above. This data is useful for querying, but it would also be nice to query by a site’s name, description, or other piece of data at a global level.

Example: In the list table that displays all the sites of a network, it’s possible to query by a site’s domain or path, but not by it’s actual name. In a large network, a user may find it difficult to find a site when many sites share similar domains or paths. The user may know the site’s title, but not the address itself.

There is no real workaround for this issue in core right now as each site’s name is stored individually in that site’s wp_#_options table and cannot be queried collectively.

Possible approaches:

  • Migrate these properties into wp_blogs() from wp_#_options as additional fields.
  • Migrate these properties into a global wp_blogmeta table.
  • Migrate these properties into another shared global space.

Feedback please

Please leave any thoughts you have on possible approaches to these 2 problems. It would be especially helpful to identify some use cases that may not yet be clear, or approaches that are not listed above. All feedback is welcome. 🙂

#multisite, #rest-api

Improving the REST API users endpoint for multisite in 4.7.3 and 4.8

Multisite office hours are held every Tuesday at 17:00 UTC in #core-multisite. The next will be Tuesday 17:00 UTC.

Improving the users endpoint was the main focus of this week’s office hours. The following is a recap of the decisions from that discussion. Please leave your feedback in the comments on this post. Related meeting notes are available from the January 10th office hours and the January 3rd office hours.

Chat log

Attendees: @iamfriendly, @sergeybiryukov, @flixos90, @ssstofff, @vizkr, @jnylen0, @nerrad, @johnbillion, @jeremyfelt

4.7.3

Some small changes to the users endpoint for multisite should be made in 4.7.3. The ticket for these changes is #39701.

  • Fail when a GET request is made to site.com/wp-json/wp/v2/users/<id> and that user is not a member of the current site.
  • Fail when a PUT request is made to site.com/wp-json/wp/v2/users/<id> and that user is not a member of the current site.

The expectation for the users endpoint in 4.7.3 is that only users from the current site can be listed or managed in any way via the REST API. Global access to users will not be available, even to global administrators (super admin).

4.8

The users endpoint will be improved significantly for the 4.8 release, ideally providing full compatibility with how users are currently managed in a multisite configuration. The ticket for this task is #39544.

Here are the expectations for the users endpoint in 4.8:

  • POST to site.com/wp/v2/users/ with an existing global user’s email address adds the existing global user to a site.
  • POST to site.com/wp/v2/users/ with complete new user data creates a new global user.
  • GET to site.com/wp/v2/users/ with a global parameter set to true lists all global users.
  • GET to site.com/wp/v2/users/ without a global parameter lists only the site’s users.
  • GET to site.com/wp/v2/users/<id> with a global parameter set to true lists data for a global user, even if they are not a member of the site.
  • GET to site.com/wp/v2/users/<id> without a global parameter lists data for a user only if they are a member of the site.
  • PUT to site.com/wp/v2/users/<id> with a global parameter set to true updates a global user and data for a user that is in the global context.
  • PUT to site.com/wp/v2/users/<id> without a global parameter updates a data for a site user that is in the site context. This is how role data can be passed to maintain a user’s relationship with the site.
  • DELETE to site.com/wp/v2/users/<id> with a global parameter set to true deletes the user completely.
  • DELETE to site.com/wp/v2/users/<id> without a global parameter removes the user from the site.

Note that while users exist in a global context, data attached to these users can exist in the global context (e.g. email address) or in a site context (e.g. site role). There may need to be a method for registering user meta in a way that specifies whether it should be treated as global or site data.

Much of the work for 4.8 is still fluid. Please leave feedback on this approach in the comments and join office hours in #core-multisite on Tuesday 17:00 UTC!

#multisite, #networks-sites, #rest-api

Providing a REST API sites endpoint for multisite

One of the objectives for multisite is to determine how sites can be managed with the REST API. This has been an agenda item for the last two weeks and quite a bit has been processed. This will continue to be a topic, so please stop in for #core-multisite office hours on Tuesday 17:00 UTC and please leave your feedback in the comments on this post.

January 17 chat log and January 24 chat log in #core-multisite

Attendees: @kenshino, @vizkr, @danhgilmore, @iamfriendly, @flixos90, @schlessera, @sergeybiryukov, @pbearne, @paaljoachim, @streetlamp, @jnylen0, @loreleiaurora, @maximeculea

The requirements for the /sites/ endpoint can be summed up with these assertions:

  • The /sites/ endpoint should provide a useful set of data for each site without requiring the use of switch_to_blog().
  • It should be possible to query /sites/ for something other than ID, domain, and path.

In its current state, any /sites/ endpoint is limited to the fields in the wp_blogs table. Data such as a site’s name and description are stored in each individual site’s wp_#_options table.

Given a list of 20 sites, switch_to_blog() will be used 20 times so that get_option() can be used to retrieve things like home, siteurl, blogname, and blogdescription. An example of how inefficient this is can be found in the generation of the My Sites menu. Caching has gotten better with the introduction of WP_Site and WP_Site_Query, but there is an opportunity to change how the information is stored.

In #37923, @johnjamesjacoby suggests the introduction of a wp_blogmeta table that provides access to some site information in a common table. After discussing this in the January 17 chat, @iamfriendly and @flixos90 agreed to each take a look at core’s default options stored in wp_options and determine which made sense in a shared wp_blogmeta table. Richard’s results can be found in a comment on the ticket and Felix’s in the Slack discussion.

After some discussion in the January 24 chat, that list can be pared down a bit more.

  • home
  • siteurl
  • blogname
  • blogdescription
  • admin_email

The creation of a new table, wp_blogmeta, and migration of data for each site from wp_#_options is something that needs feedback. Without this change, a /sites/ endpoint is still possible, but may be limited. With the change, a /sites/ endpoint is much more useful, but requires a careful migration process.

#multisite, #networks-sites, #rest-api

Controlling access to REST API user functionality for multisite

Following last week’s discussion in #core-multisite (read the recap) this week’s office hours agenda was to continue the chat about the multisite-related enhancements for the REST API users endpoint, focussing heavily on how to access the required functionality. Here is a wrap-up of the discussion.

Chat log in #core-multisite

Attendees: @jeremyfelt, @jnylen, @nerrad, @ipstenu, @earnjam, @kenshino, @maximeculea, @mikelking, @lukecavanagh, @flixos90

Now that the way on how one should be able to modify user roles per site was clarified last week, this week the focus laid on where one should be able to perform those actions. The current state of the wp-json/wp/v2/users endpoint in multisite is:

  • The users overview accessible with a GET request to wp-json/wp/v2/users only lists users that are part of the current site.
  • When creating a user with a POST request to wp-json/wp/v2/users, that user is created and added to the current site. When providing the roles parameter, the passed roles are added to the user, otherwise the user will still be part of the site, but without any role. See #38526 for background.
  • It is possible to both read and edit any user from any site with a request to wp-json/wp/v2/users/<id>, regardless of whether the user is part of that site.
  • A DELETE request to wp-json/wp/v2/users/<id> results in an error. See #38962 for background.

After the discussion about how to be able to add a specific user to a site, update their site capabilities and remove them from a site, this week’s chat revolved around where these actions can be accessed, as they are for the most part network-specific actions not available to a site administrator. The approach that was agreed on is:

  • The users overview at wp-json/wp/v2/users should continue to only show users of that site by default, but a request like wp-json/wp/v2/users?global=true should show all users in the WordPress setup. This parameter must only be available to network administrators though, more specifically users with the manage_network_users capability. In the future a network parameter might also be introduced for support of multi networks, but at this point core does not support querying users per network. Accessing global users should be available from all sites in a setup instead of only from the main site. While this approach makes these endpoints duplicates of each other, it has several benefits like preventing the requirement for cross-domain requests, allowing easier API discovery and not requiring the main site of a setup to be exposed to REST API calls to a sub site.
  • Assigning an existing user to a site and removing a user from a site should generally be only available to network administrators, and the site administrators of the site that is being interacted with.
  • Similarly, editing a user that does not belong to the current site should only be possible for a network administrator. Currently this is available to site administrators as well which is probably wrong.
  • Deleting any user completely should only be available to a network administrator. A good way to handle the reassign parameter needs to be found though.

Before coming to the conclusion that dealing with multisite functionality at the existing users endpoint, the possibility of introducing a multisite-specific endpoint only available on the main site was discussed. However this was considered not practical due to the nature of how users work in WordPress. Having separate endpoints for other network-wide functionality might still be a possibility though as long as that component solely affects the network admin, so this idea is something to keep in mind for thought about further network functionality endpoints in the future.

Back to the users endpoint, one related question that came up is:

  • Should the sites a user belongs to be available at the wp-json/wp/v2/users endpoint or at a future wp-json/wp/v2/sites endpoint? If they were available in the wp-json/wp/v2/users endpoint, every user entity would have a new sites key available if the current user had sufficient permissions to see these. If they were available in the wp-json/wp/v2/sites endpoint, that endpoint could easily support this functionality through usage of a user parameter.

@jeremyfelt suggested to look at the “Add New User” screen in the site admin to have a good use-case for how to scaffold the multisite functionality of the API endpoint. This has helped during this week’s office-hours and can also be beneficial in the future. Eventually this screen should be revamped entirely, being powered by the REST API.

Regarding the enhancements of the users endpoint, a general ticket for this task was opened at #39544. This ticket is meant to be used for discussion on the topic, while separate smaller tickets should be opened for actually implementing the individual pieces. For now feedback is welcome on that ticket. The discussion on multisite improvements for the REST API will continue at Tuesday 17:00 UTC.

/cc @rmccue and @kadamwhite

 

 

#multisite, #networks-sites, #rest-api, #users

Improving the REST API users endpoint in multisite

One of the objectives for multisite is sorting how users are managed with the REST API. This was one of the agenda items for last week’s #core-multisite office hours and generated some good discussion. Here’s a wrap-up of the ideas and thoughts from that discussion.

Chat log in #core-multisite

Attendees: @iamfriendly, @johnjamesjacoby, @nerrad, @florian-tiar, @mikelking, @earnjam, @jeremyfelt

Users in multisite exist globally and are shared among sites on one or more networks. Users are associated with sites in the user meta table with a wp_#_capabilities key.

The current state of the wp-json/wp/v2/users endpoint for multisite is:

  • A POST request for a new global user to the main site creates the user and associates them with the main site only.
  • A POST request for a new global user to a sub site creates the user and associates them with the sub site only.
  • A POST request for an existing global user results in an error.
  • A PUT request for an existing global user to a sub site updates the user’s meta with a capability for that sub site.
  • A DELETE request on multisite is invalid and results in an error. See #38962.

It is not possible to remove a user from an individual site or to delete the user from the network.

Previous tickets: #38526, #39155, #38962, #39000

The following are a few thoughts expressed separately from the above summary.

  • The right way to associate existing objects over the REST API is with a PUT request.
  • The right way to disassociate existing objects is with a PUT request.
  • Linked previous discussion – “Deleting an item should always delete an item
  • We already have functions like remove_user_from_blog() and add_user_to_blog() available to us.
  • Does “add” invite or literally add? This can probably be included as data in the PUT request.
  • What happens if an API client is built for single site and then that site gets switched to multisite?
  • Handling bulk actions on an endpoint would be nice. (e.g. Add a user to multiple sites) No endpoint has implemented batch handling yet though.

Initial tasks:

  • It should be possible to remove a user from a site with a PUT request to the wp-json/wp/v2/users/# endpoint.
  • It should be possible to delete a global user with a DELETE request to the wp-json/wp/v2/users/# endpoint once all sites have been disassociated.

New tickets will be created soon for these tasks. Please leave any initial feedback in the comments on this post covering the assumptions and conclusions made above. There will be another round of discussion during tomorrow’s #core-multisite office hours at Tuesday 17:00 UTC.

/cc @rmccue and @kadamwhite

#multisite, #networks-sites, #rest-api, #users

Focus Tech and Design Leads

There are three main focuses this year: the REST API, the editor, and the customizer.

For the REST API we’re going to work on getting first party wp-admin usage of the new endpoints, and hopefully replace all of the core places where we still use admin-ajax.

The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.

The customizer will help out the editor at first, then shift to bring those fundamental building blocks into something that could allow customization “outside of the box” of post_content, including sidebars and possibly even an entire theme.

Each focus will have a tech lead, and a design lead, and I’ll be working closely with each to make sure we’re aligned and moving diligently in the right direction even though we don’t have the normal release hooks. These starting leads will be:

REST API: Ryan McCue and KAdam White.

Editor: Matias Ventura and Joen Asmussen.

Customizer: Weston Ruter and Mel Choyce.

Given there is no set timeline for releases that would normally set a term, these leads are free to bow out at any time they feel they can’t contribute fully and we’ll find a replacement.

You might be wondering what each lead is responsible for. The REST team gave some thought to this for their focus, and this is the list they came up with:

Tech Lead responsibilities:

  • identify and ensure implementation of first-class REST API usage within WP-Admin,
  • replacing/refactoring admin-ajax use.
  • overall REST API architecture
  • infrastructure and endpoint performance
  • security at an infrastructure and endpoint (data-exposure) level
  • improving authentication options and documentation
  • working with the Design Lead to build new, or expand on existing, endpoints
  • working with the Design Lead to address usability feedback for the infrastructure and endpoints

Design Lead responsibilities:

  • usability of endpoints for internal or external clients
  • usability of the infrastructure from the perspective of a API client
  • working with the Editor and Customizer focus teams to collect requirements and gather feedback
  • identifying ways to improve the overall experience for folks building clients or consuming endpoints (like documentation)

#customizer, #editor, #rest-api

REST API: Agenda for October 24 Meeting

Here’s the agenda for Monday’s weekly meeting for the REST API project, at 2016-10-24 14:00 UTC in the #core-restapi channel in slack. The meeting will run for one hour.

  • Discuss post-merge Process Changes & the future of the WP-API GitHub Repository
  • Review Trac tickets: what hasn’t been migrated from GitHub?
  • Clarify priorities & responsibilities leading up to Beta 1
  • Open floor.

Meetings are every Monday at 1400 UTC. See you there!

#4-7, #agenda, #rest-api

WordPress REST API Success Metrics

This post is part of the conditional merge of the WordPress REST API.

Tracking and measuring specific success metrics is a priority for the WordPress REST API Content Endpoints project. The aim is to be able to look back at the implementation of the feature project to see how it went after the fact, and to utilize that information to inform future decision making.

A submission form will be created to help track implementations, in addition to automated scripting and analysis. Feedback will be grouped based on which metric it applies to. Developers and implementers will be polled to determine usage, where automation is a challenge.

It is very important to note prior to analyzing individual goals, that these goals and the achievement of them does not automatically indicate success, or that not achieving them means a lack of success. For instance, one metric that’s very hard to capture in goals like those that follow is the impact of a singular implementation. One highly impactful implementation could indicate a great deal of success, but would not be fully captured by the following metrics. These goals are established to help identify success metrics that would offer clear insight on the project, but they are not all encompassing or definitive alone.

Metric #1: Plugin utilization

Per the “Popular” plugins page of the WordPress Plugin Directory, the following can be determined:

  • 21 plugins have 1m+ active installs
  • 126 plugins have 200,000+ active installs
  • 232 plugins have 100,000+ active installs

Many of these are not good candidates for utilizing the REST API, but there are a number of plugins that are.

The following goals are proposed:

  • 15% utilization of plugins with more than 1 million installs.
  • 7% utilization of plugins with more than 200,000 installs and fewer than 1 million.
  • 3% utilization of plugins with more than 100,000 installs and fewer than 200,000.

Additionally, it is proposed to seek 5-10 examples of non-directory or otherwise prominent plugins, that may not fit the above metrics, to showcase their utilization of the API, and how it has benefited them. This may include commercial plugins.

Timeline for analysis: three major releases after merge (5.0 release day).

Metric #2: Distributed theme utilization

Popular themes are a bit of a misnomer in the WordPress landscape. The default themes or themes that have been around for a very long time account for a significant percentage of all active themes. And feature development isn’t as common for existing themes as it is for existing plugins.

In addition to polling free theme makers, top theme shops (according to Alexa) should be polled to determine usage of the API for theming purposes.

Additionally, coordination can occur with the Theme Review Team to identify usage of the API in newly submitted themes, to determine adoption.

The API could be useful in themes themselves, as well as complimentary plugins, which are not likely to be picked up by the plugin analysis. However, it’s difficult to know exactly how WordPress themes may use the content endpoints in a distributed theme context. It could be part of efforts within the customizer, page building, custom widgets, etc.

A goal of 2% adoption of the API in new themes is proposed, determined within three major releases, and analyzed amongst distinct ecosystems:

  • New WordPress.org theme review submissions
  • Third party theme shops (A shop using the API in any capacity, likely new releases, would count as “yes”, rather than theme by theme)
  • Analysis of page builder or helper plugins
  • Distinct theme communities with “builder”, “framework”, or “starter” themes.

Metric #3: Custom development implementations

The WordPress REST API is immediately useful for custom development projects, where the developer has control over the environment. The REST API in core provides a vote of confidence to outside developers that they are building with an API that has the full backward compatibility and stability expected of features in the core project.

It is proposed to identify 50+ projects in production or under development utilizing the Content Endpoints, within two major release cycles.

The likelihood is that there will be far more consumption-only applications, versus those that manipulate content. Within the same two release timeframe, the goal is to identify at least 12 custom projects that utilize the Content Endpoints beyond a read-only use case.

Metric #4: Core development and feature projects

The WordPress REST API can aid core development and feature projects. Items like Quick Draft, Press This and a menu bar revisions browser are test cases for using the API in a core context with WordPress 4.7.

Utilization of the API for additional core features and feature projects will be tracked over the next three major release cycles. It is proposed to identify 6 core features or patches than can utilize the API, as well as 1 feature project, within three major releases.

#4-7, #rest-api

REST API Team Meeting Notes, 2016-10-17

As a reminder, in just 30 minutes there is a meeting in #core to decide whether the REST API Content Endpoints will be merged as a part of WordPress 4.7! See the ongoing discussion of this proposal here. Note that the OAuth server is no longer proposed for merge at this time, but authentication options will be a primary focus area for the API project during the 4.8 development cycle.

The REST API Content Endpoints provide a new foundation upon which the WordPress developer community can build themes, plugins, and core feature. They represent a common standard and consistent interface across WordPress’s core content data types, and provide robust support for custom post types and meta values. These endpoints lay the foundation upon which future releases will add remote authentication options, even deeper querying abilities, and broader endpoint coverage for site management. This iterative approach fits WordPress’s development model and philosophy, advancing the project’s long-term goal of opening WordPress up to a wider developer audience and helping to ensure continued work on the REST API in the release cycles and years to come.

Meeting Notes

At today’s weekly API team meeting in core-restapi (agenda here) the team resolved all outstanding decisions milestoned for the REST API 2.0 / WordPress 4.7 merge candidate:

  • The ?filter query parameter will be removed from the REST API plugin prior to core merge, a breaking change that improves the consistency of querying the API and eliminates a set of parameters that could introduce backwards compatibility issues were they to be committed to WordPress core. A separate plugin will be published to reinstate the `filter` parameter on a strictly opt-in basis.
  • Comments on password-protected posts are being deferred as a future enhancement until a robust solution is proposed that permits the API to adequately mirror existing functionality.
  • The unfiltered_html capability should be respected by the API, and a patch will be submitted to bring the API’s behavior in line with core’s.

There are 29 tickets left in the 2.0 milestone, several of which have open pull requests already. These issues represent a mix of outstanding bugs, documentation needs and improvements that will be moved to trac should the merge proposal be accepted.

The REST API team leads would like to recognize that the content endpoints plugin now has 95 contributors: thank you and welcome to all of the new participants who have joined the project in the past week!

#4-7, #meeting-notes, #rest-api

Merge Proposal Discussion: REST API Content Endpoints

There are discussion meetings and office hours in #core-restapi at 2016-10-14 14:00UTC and 2016-10-14 19:00UTC on Friday the 14th. Our next team meeting is on 2016-10-17 14:00UTC. Please attend some of all of these, because

We are meeting at 2016-10-18 01:00 UTC to make a decision on this merge proposal!

To that end, the below discussion points will be updated regularly, please leave comments on this post or join the conversation in #core-restapi.

Yesterday at the dev chat the API Team proposed the Content API Endpoints for merge in WordPress 4.7. There was popular support for this feature but as @jorbin and @helen noted that the lack of dissent suggested additional review is needed, so the API Team is continuing to seek thorough review & constructive criticism of the content endpoints, including the open questions previously shared on the week 7 and week 8 API team updates.

The merge proposal also engendered follow-up discussion in the #core-restapi channel about the benefit content endpoints bring to core, whether having such endpoints built in is quantifiably more beneficial than having them as a plugin, whether moving development from a plugin to core would slow development, and whether the endpoints as-proposed have been sufficiently reviewed for security and performance. We attempt to capture those questions & concerns (and the perspectives on them) below.

Security

Have the content API endpoints been thoroughly reviewed for security?

  • The REST API plugin has been on HackerOne for over a year with paid bounties for bugs
  • @barry has begun a security review

Performance

How does the API measure up against alternatives? Are there concerns about how the API could impact the servers to which it is deployed?

  • DeliciousBrains did a performance comparison with Admin AJAX and found the REST API to have a performance improvement (These tests have not yet been independently verified)
  • @mikeschroder notes in the comments that using the REST API in place of Admin-Ajax will also bring speed benefits by permitting many previously-uncacheable requests to be cached.

User Feedback

Are the content endpoints sufficiently well-tested & vetted by the community?

  • @matt questions whether feedback is coming too late in development for concerns to be acted upon
    • @rmccue notes that the v2 endpoints were created based on user feedback; REST API endpoints are being deployed by plugins and running on VIP, and the content endpoints have been in wide use across a variety of sites, leading to 90+ code contributors and far more developers’ support & feedback on the endpoints
  • @rmccue has also reached out to Phil Sturgeon for feedback and will follow up

Do Content Endpoints Benefit Core Development?

Will having these endpoints in core improve future core development, or solve any immediate problems?

  • @bradyvercher suggested that the content API endpoints would remove the need to write a variety of one-off ajax callbacks when developing future WordPress Core AJAX functionality
  • @westonruter notes that the customizer could dynamically create settings for posts and other kinds of content without having to wire up new admin-ajax handlers

Will Merging Negatively Impact API Development?

Will having to work through trac instead of GitHub cause development to atrophy?

  • @jjj argues that merging will slow development, because GitHub-hosted plugins are not bound to WordPress release cycles and have less overhead for features to be developed and deployed for testing. @jjj requested a plan for how the REST API will be developed going forward after the merge of these endpoints that would account for the added friction.
  • @krogsgard countered that core increases the visibility of a project like the content endpoints
    • The number of new contributors in this Slack discussion suggests that this merge proposal is bringing in new voices; whether this supports Brian’s point or not, the team is grateful for the breadth of perspectives being shared -Ed.
  • @rachelbaker suggested that the API endpoints are sufficiently inter-dependent with core WordPress code that maintaining the plugin separately amounts to maintaining a fork, and that such separated development is untenable long-term.
  • @matt hopes that a merge of these endpoints would slow release speed, but not development speed; @rmccue feels that development speed will stay the same or increase, and that tying releases to WordPress Core increases the stability and predictability of the API endpoints.
  • The versioning of the API endpoints supports forward compatibility

Do Content Endpoints Belong on Every WordPress Site?

What are the pros and cons to having every WordPress site have content API endpoints?

  • @rmccue suggests the API has network effects that can only be realized with a large install base. @krogsgard draws a comparison to RSS, the widespread availability of which enables everything from podcasting from WP to the use of apps like Feedly.
  • @matt suggests that the Atom API is a better analogue than RSS, which is an independent and pre-existing standard, and that network effects could be tested through inclusion in Jetpack
  • @joostdevalk notes that many plugins, like Yoast, have data tied to existing content such as posts and pages; either they expose the content through their own endpoints, or core does. If Core exposes content types through the API then plugins may build on top of that shared foundation, not independently reinvent the wheel. “if this doesn’t end up in core, we’ll start rolling our own API for stuff. Others will too. Interoperability won’t be there, for even the most basic stuff. I think this isn’t like RSS, I think this is much more like all of us using the same table space in MySQL.”
    • @shelob9 and @masonjames agree that merging the endpoints would create a consistent and reliable open “standard” that WordPress developers can use instead of continually reinventing how to read and edit post data over HTTP.
    • In response to the question “what prevents you from building on the endpoints in their plugin form,” @joostdevalk went on to note that plugin dependencies would make that a viable option, but that burden currently lies on the user. Plugin installation is not frictionless.
  • Can these endpoints be bundled? short takeaway: no
    • Woo bundled the API infrastructure before it was merged; doing so for content endpoints would require bundling prohibitively large amounts of endpoint code.
    • @nerrad worries that if plugins bundle different versions of the endpoints plugin, then those plugins may conflict if all bundled copies are not kept in sync.
      • @nerrad clarifies in the comments below that these worries also encompass the additional risk of conflicts when plugin authors each build their own versions of these content endpoints, instead of leveraging a shared standard: if two plugins each expose their own REST collection for posts, a developer working on a site with multiple such endpoints will need to decide which to extend, and will then have their extension tied to that specific plugin rather than to a core API.
  • @schrapel and @jorbin discussed that these content endpoints make it much easier to crawl a site, which also brings some potential performance concerns: no new content is exposed, but the process of aggregating it is easier and more easily automated.
  • In the  comments below @foliovision believes that merging the endpoints will be the best way to assert the level of back-compatibility that mid-size agencies need in order to confidently utilize the endpoints.

Please leave thoughts, questions, concerns, comments & experience in the comments below. Thank you!

Edited 2016-10-16 to include the below comments into the body of the post

#4-7, #rest-api