Since the WordPress REST API was first proposed, we’ve talked a lot about how it will be involved in the future of wp-admin. Gutenberg, the new WordPress UI system that will be used for the new post editor in WordPress 5.0 is the first example we have of the REST API being used to communicate data between the server and a JavaScript-driven interface.
A JavaScript-driven interface communicating with WordPress via the REST API or GraphQL inside of wp-admin is something that’s been talked about and written about a lot. Many plugins do this already. But Gutenberg is the most expansive use of this pattern we’ve seen yet in core.
This article is a high-level overview of how the WordPress REST API is used by Gutenberg. I will provide links to where you can learn more about each concept.
Saving Posts
The WordPress REST API is used by Gutenberg to create and update posts. The REST API uses wp_update_post() to update the post, so all hooks you’d expect to fire will still fire.
The documentation on metaboxes gives a detailed overview of the lengths that have been taken to ensure that all of the same hooks fire during rendering the post editor and saving data from it as we had in the older versions of WordPress.
The Schema Of Posts
Last year I wrote an article about how to use the WordPress REST API to query for and format posts or other data, without a separate HTTP request. When editing a post with WordPress, the post’s JSON is added as inline JavaScript. If you look at where that happens and read back in the code a bit, you’ll find the function gutenberg_get_post_to_edit. That function does something very similar to what I covered in that article — create a JSON representation of a WordPress post in the schema defined by the WordPress REST API.
You shouldn’t access the variable Gutenberg creates. Instead, you can access the current post — in it’s most up to date state — using wp.data.
What’s important here is that WordPress posts in the context conform to the schema defined by the WordPress REST API. The way the REST API formats posts, that’s what posts look like.
Version 2 of the WordPress REST API represents many items, such as post title, post excerpt and post content with an object that has at least one index “rendered”. Rendered as the rendered HTML of the post.
With Gutenberg, if the current user has the edit_posts capability there will also be a “raw” index, that has the unparsed markup. This information is only shown to those who could see the post editor as post content may contain sensitive information. For example, a block may have logic to display different information based on user role. This new feature may be useful for fragment caching or building alternative parsers.
It’s also worth noting that the schema for a REST API route’s endpoint arguments crosses over with the schema you use when registering a Gutenberg block attribute.
Meta Data In Blocks
There are ways you can store block attribute data in a variety of ways, including saving the data as post meta. When you register a block attribute that uses meta storage, you will need to specify what meta key to use. That key should be registered using register_meta.
I recently covered using register_meta and other topics related to using metadata and other types of custom fields with the WordPress REST API. Once a meta field and block attribute are registered with the same field, the rest is handled automatically.
One of the most out of date parts of WordPress has been how meta box data is saved. There is a very detailed explanation of how it works now in the handbook. Previously developers of custom metaboxes were responsible for authorizing, sanitizing, and validating the metadata on read and write. Now a declarative API causes the rest of it to happen in the background. This means a lot less repetitive work is going to be needed to be done by developers. This task that’s handled in core is in an area that mistakes leave to security and privacy issues.
New Possibilities
If you’re feeling like learning all of the new stuff in Gutenberg is a lot, keep in mind everything you know about the REST API is even more important because of Gutenberg. Gutenberg is largely a client-side application. It doesn’t need too much server-side code for interacting with that client because the REST API is already there.
If you want to change the data during creation, reading, updating or deleting of a post by Gutenberg, use what you already know about the REST API.
This also makes a huge difference in how you work with data in the front-end. As we’ve seen, WordPress posts now “look like” how the REST API represents it we can use the same data structure for front-end and admin display of an interface or the information it shows. Or we can use the same code in both places or part of it. There are a lot of new possibilities that come with upgrading our tooling to use modern tools including a REST API.
4 Comments