Gutenberg and the REST API, early May

Since I last wrote two weeks ago, we’re making progress! Key achievements for Gutenberg and the REST API include:

  • Support for who=authors was added to GET wp/v2/users, making it possible to accurately query for authors. WordPress, for better or for worse, defines an author as user_level!=0. See WordPress/gutenberg#6361 for the context on why we can’t add this logic client-side (#42202 for WordPress 4.9.6).
  • Improved performance for the _fields= query parameter (e.g. GET wp/v2/pages?_fields=id,title) by ensuring WordPress core will only process the fields requested for the response. Notably, this helps us avoid running the_content when we don’t need to be (#43874 for WordPress 4.9.7).
  • Minor enhancements to reflect existing WordPress behaviors:

The “Merge Proposal: REST API” GitHub milestone represents the distance we still need to close. Slowly, steadily, we’re bridging the gap, but we could use your help. Here are some of the issues we’re still working through:

  • To ensure all necessary data is available to Gutenberg, we’ve settled upon permitting unbounded per_page=-1 REST API requests for authorized users. This landed for GET wp/v2/users (WordPress/gutenberg#6627), is in-progress for GET wp/v2/(pages|blocks) (WordPress/gutenberg#6657), and needs to be addressed for categories, tags, and custom taxonomies. We also need to patch core with this enhancement (#43998 for WordPress 4.9.7?)
  • Capabilities can’t be processed directly client-side (WordPress/gutenberg#6361), so we’ve introduced a new targetSchema concept to communicate which actions a user can perform. See it in action with wp:action-sticky (WordPress/gutenberg#6529) and wp:action-assign-author (WordPress/gutenberg#6630). There are a few other actions we will need to work out, and then we’ll need to patch core (no ticket yet).
  • @adamsilverstein is putting together an improved autosaves implementation (WordPress/gutenberg#6257) that I literally cannot wait to see complete. I’m sure he could use some help testing in the near future.
  • @flixos90 is implementing a WP_REST_Search_Controller endpoint (WordPress/gutenberg#6489) to power the link search UI.

Join us tomorrow, Thursday, May 10 at 17:00 UTC in #core-restapi office hours if you’d like to chat through any questions you have.

#gutenberg, #rest-api

Your help wanted: Gutenberg Migration Guide

Happy Thursday 🙂

I’ve started a new crowdsourcing project, the Gutenberg Migration Guide, to document WordPress Classic Editor customization points and their Gutenberg equivalents (if such exist).

For example, the media_buttons action is a common way to add a button atop the editor:

Its Gutenberg-equivalent is the Block Inserter. Converting a media button to the Block Inserter requires registering a block type. And now we have a corresponding page for developers to reference.

media_buttons is only one of the many ways the Classic Editor can be customized. Wouldn’t it be great if there was a database covering all of them?

This is where you come in! Take a look through the Gutenberg Migration Guide. For each action, filter, and so on, we’d like to document real-world examples of how they’ve been used. Then, for each of those real-world examples, identify how the feature might be replicated in Gutenberg.

Have a new hook to suggest or question to ask? Please open a new GitHub issue and we’ll get it sorted.

Gutenberg, REST API, and you

Fancy yourself some challenging architectural puzzles? Have we got the ticket for you!

As you may know, Gutenberg uses the WordPress REST API as a bridge between the land of JavaScript and land of PHP. There were a whole host of conceptual challenges in translating WordPress internals to REST — and even more we still haven’t solved!

We’d love your help 🙂 Read through and comment on the issues linked below as you have time. Then, if you’re available, join the next REST API office hours for a rousing conversation: Thursday, April 26 at 17:00 UTC

Even more curious? Dive into the entire Gutenberg REST API milestone and all Trac tickets tagged ‘rest-api’.

Thanks!

Introducing the Gutenberg Plugin Compatibility Database

Ideally, the majority of WordPress users should be able to use Gutenberg on the day WordPress 5.0 is released. They'll hit "Update WordPress", navigate back to the editor, and continue publishing in Gutenberg with all of the functionality they expect in the Classic Editor.

But plugins! If any one of their active plugins are incompatible with Gutenberg, the WordPress user is likely to experience pain, misery, and bad fortune. Many WordPress installations have a dozen or more active plugins, so WordPress plugins are a significant risk vector for Gutenberg incompatibility.

Enter the Gutenberg Plugin Compatibility Database. The goal for this crowdsourcing tool is to identify whether or not WordPress.org plugins are compatible with Gutenberg. With this data set, we'll be able to:

  • Know the most likely causes of incompatibility.
  • Focus developer outreach on the highest impact problems.
  • Proactively educate WordPress users on whether or not their WordPress installation is ready for Gutenberg.

The only gotcha: we need lots and lots of person-hours for testing. If each plugin takes roughly 1 minute to test, we'll need ~75 person-hours to get through the remaining ~4500 plugins in the database.

Check out the project README.md for a more complete introduction to what's involved. This includes a definition for "Gutenberg-compatible", explanation for why only 5000 plugins are in the database, and other design decisions.

Do you or someone you know have access to lots of person-hours (e.g. WordCamp contributor day, hosting support team, etc.)? I'd love to chat! Feel free to leave a comment, ping me on WordPress.org Slack (I'm 'danielbachhuber'), or get in touch however most convenient.

WP REST API: Versions 2.0 Beta 12.1 and 2.0 Beta 13.1

WP REST API Versions 2.0 Beta 12.1 and 2.0 Beta 13.1 are security releases to address a data privacy issue with the Users endpoint. Given certain parameters, private user data such as email addresses may be exposed to unauthenticated users.

This release was coordinated by the REST API team and the WordPress core security team. The security team is pushing automatic updates, but do not wait or rely on the automatic update process. We recommend sites or plugins that are using either 2.0 Beta 12 or 2.0 Beta 13 to update the plugin immediately. Download your respective version from WordPress.org or Github.

Thanks to James Kettle (PortSwigger Web Security) via HackerOne for reporting this issue to the team responsibly, and to David Remer (websupporter) for inadvertently fixing this issue on Github.

If you believe you have discovered a potential security vulnerability with the WP REST API, please disclose it to us privately by sending an email to security@wordpress.org. Security issues can also be reported via HackerOne.

#rest-api

WP REST API: Version 2.0 Beta 12

Happy Tuesday 🙂 The WP REST API team is proud to bring you: 2.0 Beta 12 “Canyonero”. Download it from the plugin repository or from GitHub.

Here are some highlightsbreaking changes from the changelog:

  • Removes meta endpoints from primary plugin. If your project depends on post meta endpoints, please install WP REST API Meta Endpoints. For the gory history of meta, read #1425 and linked issues. At this time, we recommend using register_rest_field() to expose meta (docs).
  • Returns original resource when deleting PTCU. Now that all resources require the force param, we don’t need to wrap delete responses with the trash state.
  • Uses roles rather than role in the Users controller. Building the REST API gives us the opportunity to standardize on roles, instead of having both roles and role.
  • Moves to consistent use of context throughout controllers. Contexts limit the data present in the response. Here’s how to think of them: embed correlates with sidebar representation, view represents the primary public view, and edit is the data expected for an editor.
  • Removes post_* query param support for GET /wp/v2/comments. The proper pattern is to use GET /wp/v2/posts to fetch the post IDs to limit the request to.
  • Introduces rest_validate_request_arg()/rest_sanitize_request_arg(). Dedicated functions means we can use them for validating / sanitizing query args too. Removes WP_REST_Controller::validate_schema_property() and WP_REST_Controller::sanitize_schema_property().

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

What’s the future of the WP REST API? I’d like to leave you with this final thought:

What came first, the chicken or the egg?
I egged the chicken, and then I ate his leg

#feature-plugins, #json-api, #rest-api

Thar be a WP REST API meeting tomorrow

Curious as to when the WP REST API endpoints will land in WordPress core? Me too!

We’re meeting to discuss the State of the REST API just under 24 hours from now in #core-restapi on Slack: Thursday, February 4 at 23:00 UTC

The primary points of discussion are:

  • Existing Post, Term, User and Comment endpoints.
  • New Site, Widgets, Menus, Plugins and Themes endpoints we started on Friday.
  • REST API clients — those that exist, and those that don’t yet.
  • Happy fun authentication methods.

See you there!

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 11

Just days before the first conference dedicated to the REST API, we bring you: 2.0 Beta 11 “Give me a white wine spritzer!”. Download it from the plugin repository or from GitHub.

Here are some highlightsbreaking changes from the changelog:

  • Moves Post->Term relations to the Post Resource. Previously, a client would fetch a Post’s Tags with GET /wp/v2/posts/<id>/tags. In Beta 11, an array of term ids is included on the Post resource. The collection of terms for a Post can be fetched with GET /wp/v2/tags?post=<id>. The WP_REST_Posts_Terms_Controller class no longer exists.
  • Changes featured_image attribute on Posts to featured_media. While featuring other attachment types isn’t yet officially supported, this makes it easier for us to introduce the possibility in the future.
  • Uses discrete schema title for categories and tags. If you’ve used register_rest_field( 'term' ), you’ll need to change 'term' to 'tag' and/or 'category'.
  • Makes many filters dynamic based on the controller type. If you were using the rest_prepare_term filter, you’ll need to change it to rest_prepare_post_tag or rest_prepare_category. If you were using rest_post_query or rest_terms_query, you’ll need update your use to rest_page_query, etc. If you were using rest_post_trashable, rest_insert_post or rest_delete_post, they are now dynamic based on the post type slug.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 10, with security releases

For the first REST API release of 2016, we bring you: 2.0 Beta 10 “Chief Wiggum”. Because we’ve got security releases too, Ralphie.

Security Releases

On Friday, we discovered that attachments uploaded to private posts are publicly queryable through the REST API. This is a form of information disclosure because WordPress’ permissions model is such that attachments uploaded to posts should inherit the visibility of their parent post.

All previous versions of the plugin are affected. All WP REST API users are strongly encouraged to update immediately. Many prior releases has been separately patched. If you’re still using WP-API v1.x, you can update to v1.2.5. If you’re on an older 2.0 Beta for whatever reason, we’ve tagged versions 2.0 Beta 3.1, 4.1, 5.1, 6.1, 7.1, 8.1, and 9.1.

If you believe you have discovered a potential security vulnerability with the WP REST API, please disclose it to us privately by sending an email to security@wordpress.org. Security issues can also be reported via HackerOne.

Version 2.0 Beta 10

Here are some of the highlights of Beta 10:

  • Breaking changes:
    • Removes compatibility repo for WordPress 4.3. WordPress 4.4 is now the minimum supported version.
    • Changes link relation for types and taxonomies. In Beta 9, this link relation was introduced as item, which isn’t correct. The relation has been changed to https://api.w.org/items.
    • Introduces edit context for wp/v2/types and wp/v2/taxonomies. Some fields have moved into this context, which require edit_posts and manage_terms, respectively.
    • Removes post_format as a term _link for Posts. Post formats aren’t a custom taxonomy in the eyes of the REST API.
  • Consistently query for a specified set of items. Adds include param to /wp/v2/posts, /wp/v2/users, /wp/v2/<taxonomy> and /wp/v2/comments.
  • Tons of minor improvements and bug fixes. You should read the full changelog for all of them.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api

WP REST API: Version 2.0 Beta 9

For the last REST API release of 2015, we bring you: 2.0 Beta 9 “You Don’t Win Friends With Salad”. Download it from the plugin repository or from GitHub.

Should I use 2.0 Beta 9 in production?

This is a great question. I (Daniel) will do my best to answer from my perspective — Ryan, Rachel or Joe may have different opinions.

As many of you may already know, the v1.x branch is essentially deprecated and only maintained for security and major compatibility issues. Even its latest release, v1.2.4, still includes some annoying bugs. The v2.0 Betas introduce aton of new features, functionality, and general improvements. But, there will never be a formal v2.0 plugin release — v2.0 will be endpoint inclusion into WordPress core.

Right now, we’re doing our darned best to get the endpoints into core at the end of January 2016. Between now and then we have at least 74 issues to wade through. Beta 9 includes 32 merged pull requests.

In the interest of feeling confident about the code we’re committing to core, we are and will be making breaking changes in the Betas. Significantly, Beta 10 will remove the core directory, and will be incompatible with WordPress 4.3.

Short answer: you’re welcome to use the Betas in production if you understand the ramifications. When updating, we expect you to read through the changelog and thoroughly test each release with your project. You should probably have test coverage on any custom endpoints you’re writing. And, set aside time to properly debug any issues you uncover and submit pull requests with test coverage.

If you aren’t comfortable with aforementioned ramifications, please refrain from using the v2.0 Betas in production. We do encourage everyone to use them locally, or in staging / test environments, and look forward to your feedback.

Changelog

Here are some highlights:

  • Move tags and categories to top-level endpoints. Tags are now accessible at `/wp/v2/tags`, and categories accessible at `/wp/v2/categories`. Post terms reside at `/wp/v2/posts//tags` and `/wp/v2//categories`.
  • Return object for requests to `/wp/v2/taxonomies`. This is consistent with `/wp/v2/types` and `/wp/v2/statuses`.
  • Remove `rest_get_timezone()`. `json_get_timezone()` was only ever used in v1. This function causes fatals, and shouldn’t be used.
  • Rename `register_api_field()` to `register_rest_field()`. Introduces a `register_api_field()` function for backwards compat, which calls `_doing_it_wrong()`. However, `register_api_field()` won’t ever be committed to WordPress core, so you should update your function calls.
  • Change taxonomies’ `post_type` argument to `type`. It’s consistent with how we’re exposing post types in the API.
  • Sync infrastructure with shipped in WordPress 4.4.
    • `wp-includes/rest-api/rest-functions.php` is removed, and its functions moved into `wp-includes/rest-api.php`.
    • Send nocache headers for REST requests.
    • Fix handling of HEAD requests.
    • Mark `WP_REST_Server::get_raw_data()` as static.
    • Unabbreviate error string.
  • Change terms endpoints to use `term_id` not `tt_id`.
  • Standardize declaration of `context` param for `GET` requests across controllers. However, we’re still inconsistent in which controllers expose which params. Follow #1845 for further discussion.
  • Link types / taxonomies to their collections, and vice versa. Collections link to their type / taxonomy with the `about` relation; types / taxonomies link to their collection with the `item` relation, which is imperfect and may change in the future.

As always, we have a detailed changelog as well as the full set of changes if you’re interested.

#feature-plugins, #json-api, #rest-api