REST API meeting summary, Feb 4

The core REST API team, members of the WordPress.com API team, and other interested developers met to discuss the REST API.  Full logs of the meeting are available on Slack.

Existing endpoints

The meeting opened with a discussion of the existing endpoints: what is and isn’t ready. @rmccue summarized:

• The main focus has been on the 4 “core” objects in WordPress: posts, terms, comments, and users.
• Posts
  • Password-protected posts are going to be ignored from the API until we have a good solution.
  • Meta
    • Post (and other) meta has been pushed out into a separate feature plugin led by @jeremyfelt. Discussion is on the github repo.
    • The main issue is that there’s no differentiation between meta fields. Meta could be added via the Custom Fields meta box, or by a plugin.
    • Enhancing register_meta() in core would allow opt-in to the meta REST API – requiring some core work. See the patch on #35658 for details.
    • There is no current way to explicitly register meta as public.
    • We need to support object meta (post, user, comment, term) and object types (custom post types, etc)
  • Media
    • Mostly complete (it’s a custom post type).
    • Some special handling around uploading media.
  • Autosaves and post previews
    • Tricky, but we think we have a solution for that moving forward.
    • Working on them in a separate feature plugin instead.
    • This will be an enhancement to the API in the future, and doesn’t block compatibility.
• Terms
  • Work great.
• Users
  • Works great; undergoing final review.
• Comments
  • Works; custom comment types are harder until core better supports them.

Merge proposal and discussion

An extensive discussion ensued regarding the possibility and appropriateness of merging the endpoints into core. The discussion continued for over an hour; mainly covering whether we should merge the 4 core endpoints, or wait for a complete API before merging…  and what the definition of a complete API is.

The REST API team’s proposal is that we merge the 4 core objects in the REST API with full read, create, update, delete support, then add more peripheral features when they’re ready. 

@matt argued that we wait until the API supports everything you can do in wp-admin before merging.

The discussion revolved around these proposals and what is best for the WordPress project. Would merging the existing well developed endpoints sooner help or hinder developer adoption, and further iteration/improvement? Would delaying the endpoint merge help or hinder progress?

Here are some key comments from the discussion.

• @rmccue  The approach to the API needs to change from “the API team creates all of the API” to “the API team controls the general shape of the API, and each team works with it”
• @danielbachhuber Options / a Site Resource is more easily viable, as are Plugins and Themes. Widgets and Menus essentially need to be reinvented before they’ll work in a REST API
• @jnylen It’s a question of when, and how much testing can be done first. Shipping an API that is read-only and incomplete in several key areas feels like a big mistake.
• @kadamwhite we’re shipping an API with write capabilities but only cookie-based auth will be supported OOTB.
• @matt  I would be pretty skeptical of merging a partial API into core…  no partial endpoints in core. let’s design a complete API, not half-do it.
• @rmccue The API is specifically structured around progressive enhancement
• @jorbin I think only supporting the four core object types allows for some amazing themes and amazing content editors to be created, but doesn’t allow for full wp-admin replacements. I’m ok with that.
• @jnylen From what I’ve seen so far, I’m most concerned about shipping individual endpoints with missing features.
• @jorbin I think the best way to pick up the pace is to get key things locked up and get the four core object types in core. This would help core develop API-first for those features
• @codebykat On the WPCOM side, we’re committed to taking the plunge, but we’re not there yet which means things are untested.
• @jnylen I think this needs more testing at large scale before shipping, including some of the more difficult and obscure features of WP.
• @drew Shipping with full wp-admin replacement capability is unrealistic, imo. We need something flexible and stable that developers can use as solid jumping off point. All the rest can get separately iterated.
• @mike I think that, realistically, to ship the API… we need an MVP, and I don’t think that defining our goalpost as “all of wp-admin” fits that criteria.
• @matt Full wp-admin coverage is a firm goalpost, it gives us a super clear criteria for when it should be merged into core. is everything possible in wp-admin, possible through the API?

REST API meeting summary, Feb 4 by Adam Silverstein was originally posted at https://make.wordpress.org/core/2016/02/05/rest-api-meeting-summary-feb-4/