REST API meeting summary, Feb 4

The coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. team, members of the WordPress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/ APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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.
    • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.
      • Post (and other) meta has been pushed out into a separate feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party.
      • Enhancing register_meta() in core would allow opt-in to the meta REST API – requiring some core work. See the patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. 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 typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept.).
      • 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 enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. to the API in the future, and doesn’t blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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-adminadmin (and super 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 MVPMinimum Viable Product "A minimum viable product (MVP) is a product with just enough features to satisfy early customers, and to provide feedback for future product development." - WikiPedia, 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?

#meeting-notes, #rest-api