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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. 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 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/., the infrastructure for the 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. 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 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 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 adminadmin (and super 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 trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. 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 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..
    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 fieldCustom Field Custom Field, also referred to as post meta, is a feature in WordPress. It allows users to add additional information when writing a post, eg contributors’ names, auth. WordPress stores this information as metadata. Users can display this meta data by using template tags in their WordPress themes. 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ 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 docsinline docs (phpdoc, docblock, xref) 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

  • PingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” 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 headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. 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 UIUI User interface/Design help. (@krogsgard and @kadamwhite)
  • Determine auth_callback (needs different name, has a conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved. 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 contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org. 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!

#4-7, #rest-api