WordPress REST API update

tl;dr

There’s a renewed push going on right now to try and get what is being termed “content endpoints” into WordPress core with the 4.7 release.

In the first core development meeting of the 4.7 cycle, @helen identified a series of tasks that would need to be analyzed and acted upon to be able to make a new proposal for core inclusion, including identifying existing blockers. There is a team of people actively working on these items, and your participation is wanted!

New meeting times

Regular meetings have been changed to take place at 14:00 UTC Mondays, with bug scrubs at 14:00 UTC Thursdays — all in #core-restapi. So the next meeting is Monday, September 12th, 14:00 UTC.

Fuller story and action items

If you are not caught up on the state of the WordPress REST API, the infrastructure for the API went into WordPress 4.4. Since that time, several prominent plugins are using the infrastructure to create their own REST APIs.And now the feature project (not in core) consists of core endpoints and authentication mechanisms. The four primary types of resources that have been developed are for: posts (and other post types), users, comments, and terms. There is also a Google spreadsheet where you can list sites you know of running V2 of the REST API plugin in production.

The proposal, if the various criteria are met, would request core inclusion for what we’re calling “content endpoints”, and “management endpoints” would be part of a subsequent release cycle. With the content endpoints, website developers would have tools at their disposal to build websites in whatever programming language they choose, using data from WordPress. Additionally, certain types of applications would also be able to create experiences for managing WordPress content — though not complete WordPress site management the way you can from the WordPress admin.

The primary focus areas for core inclusion of the WordPress REST API — as initially defined by Helen, and then expanded on in the core dev chat meeting — are as follows:

  1. Rigorously test 4.6 and trunk compatibility and resolve any issues that may be found.
    1. Includes reviews by current component maintainers for existing endpoints.
    2. For example: WP_Post_Types and other new objects, need compatibility.
  2. Identify and resolve some of the final “quirky” issues (e.g. password-protected posts).
  3. Create support for meta.
    1. By “meta support” in the API, we refer to meta values that have been registered by a developer. Ideally via register_meta( ...., array( 'show_in_rest' ) ). For clarity, this excludes arbitrary meta storing (i.e. a client arbitrarily using the WordPress database)
  4. Create support for options – this is not “content” per say, but imagine an app where you can’t change your site title and tagline.
    1. Needs significant clarification, definition of what should be achieved
    2. Repo for site endpoints: https://github.com/WP-API/wp-api-site-endpoints
      1. Discuss architecture for how this would work (like, site endpoints w/ object of settings) https://github.com/WP-API/WP-API/issues/816
  5. Establish a forward compatibility plan, particularly around how to avoid/minimize plugin and theme conflicts. IE: namespacing and documentation / protected stuff. Relate to current general WP best practices (IE: custom field named “likes” – possible vs good idea). Need document to outline our views.
  6. Dedicated reviews from developers with deep experience in security and REST APIs, ideally including some of the non-WP PHP community.
    1. Identify and request reviews by specific developers & subjects.
      1. Security
      2. Core compatibility
      3. Integration
      4. Consumption
      5. Non-WP developers / fresh eyes
  7. Identify current authentication options, and their viability for inclusion in 4.7. Document flows of implementing and using each.
    1. Cookie auth
    2. Basic auth
    3. oAuth 1
    4. oAuth 2
  8. Establish and document data with performance comparisons – speed, bandwidth, etc – against admin-ajax, XML-RPC, etc. (Might just require education, as really all these are pretty similar). Identify and address performance related issues on project GitHub repo.
  9. Recruit and assign new / excited contributors
  10. Align existing docs with primary project. Outline documentation needs, and create them.
    1. Get volunteers to take on specific tasks
    2. Decide where these docs go, both now and in the future

Specific initiatives

There are several more specific initiatives to work on, many of which we’ve tasked out and assigned, but plenty that could use more input.

Docs Initiatives

  • Inline docs will eventually be merged into core inline docs, so any prep there should be roadmapped along with the rest of the 4.7 planning
  • User docs on consuming the API (e.g. doing things with the routes it provides from external systems, like uploading media) are needed and should live in the docs-v2 repo for now. See issues list for current user-facing documentation needs.
  • User docs on extending within the context of the API plugin (how to add routes, how to lock down access to auth’d users) are needed and should live in the docs-v2 repo for now
  • Docs on making endpoints with the infrastructure currently in core should live within the developer handbook

Task Assignments

  • Ping component maintainers to see what testing they’ve done w/ API (@krogsgard)
  • Password game plan: relies on #16483: Blank content, rendered string, title however it is done in core now, 401 for individual posts, content to include protected:truein return object, and (maybe) give users that can edit posts access to content in response, consider Authorization header options. (@rmccue)
  • A pass at registered settings. @joehoyle has tackled this with a first draft, along with #37885.
  • Document feature detection as it works today (http://v2.wp-api.org/guide/discovery/). Establish best practice for extending with new endpoints. Establish best practice for modifying existing objects.
  • Documentation needed: compare register_rest_field() vs register_meta() and document best practice for when register_rest_field() may still be preferable. But generally encourage usage of register_meta()
  • Consideration: With register_rest_field, maybe force a namespace a la register_rest_route
  • Contact implementors from @joehoyle‘s API-in-use list to get feedback on their experience with the API (@krogsgard)
  • Document that name, description, url and home are the options already available in index as read-only. Consider change of this with global options endpoint.
  • Develop personas for user groups that interact with the API (@jorbin)
  • Interface testing for cookie and oauth1 implementations. Recruit UI/Design help. (@krogsgard and @kadamwhite)
  • Determine auth_callback (needs different name, has a conflict right now) necessity within register_meta(), as someone may want meta exposed, but only for authenticated users, and there is no cap system for read_meta.>
  • Review https://github.com/WP-API/WP-API/issues/2558 for performance gain.
  • Review https://github.com/WP-API/WP-API/issues/1625 for awkward data handling w/ client-js

Bug scrubs

The first bug scrub of this cycle took place today, and we were able to go through all open issues on GitHub that do not have a label, and label them, plus add at least some level of context. Our priority for future meetings will be to ensure that we have assigned bugs to appropriate people, and go back through and ensure we have milestones assigned to various tickets. We’ll have an open floor period during each regular meeting to discuss particular issues.

Get involved

If you have any interest in the API, your help and insights are wanted! You can join Chat.WordPress.org in the #core-restapi room to sit in and watch, or jump in to various discussions. Also, if you just want to play with the plugin and report back your experience, that’d also be super helpful.

One group of core contributors we really need feedback from are component maintainers. The team working on the REST API would like your input on how well the API currently interacts with your component, how it can improve, and to identify trouble areas that would need to be addressed both for initial core inclusion of the API, and down the road.

Thanks for listening!