The REST API in WordPress 5.0

WordPress 5.0 contains several additions to the REST API that help provide the new block based editor with all the data it needs. Let’s talk about them!

New Core Endpoints

Several new endpoints have been added to help supply the new block based editor with the data it needs. They all have been built on the existing REST API infrastructure, so the same action and filter hooks throughout can be used to modify requests and responses.

Autosaves

An Autosaves endpoint has been added and registered for all post types except attachment (but including custom post types). The endpoint utilizes the WP_REST_Autosaves_Controller class which extends WP_REST_Revisions_Controller. Registering the endpoint for all post types, and not just those with revisions, was an intentional design decision because all post types need the ability to autosave whether or not revisions are enabled.

Only id, title, post_content and excerpt are saved on this endpoint, but a full, updated post object is returned in the response. It also returns the preview_link, which drives the Post Preview button in the new editor. 

Note: This endpoint requires requests to be authenticated.

Ticket #43316

Search

In order to facilitate searching across multiple post types, a new WP_REST_Search_Controller class was added which registers a /wp/v2/search endpoint. This endpoint is used by the link inserter in the new editor. 

Search types are handled by extending WP_REST_Search_Handler. The default search type is WP_REST_Post_Search_Handler, but this can be filtered by plugins or a theme by using the wp_rest_search_handlers filter.

Ticket #39965

Block Type

A new hidden post type of wp_block has been added for storing reusable blocks. Information about the post type is available at wp/v2/types/wp_block, including the labels and the capabilities required in order to read and create reusable blocks.

Ticket #45098

Blocks

The individual reusable blocks can be retrieved from wp/v2/blocks. This uses the standard post controller to return post objects containing the rendered content and associated data of each reusable block. 

Note: This endpoint requires requests to be authenticated.

Ticket #45098

Block Renderer

All dynamic blocks with server-side rendering, such as the latest comments or archives, can be accessed at wp/v2/block-renderer/<name>. Names have to be structured as namespace/block-name, where namespace is the name of your plugin or theme. An example core endpoint would be wp/v2/block-renderer/core/archives.

All registered attributes for the block being rendered are accepted as GET parameters. These are validated against the schema matching what was declared in register_block_type().

Note: This endpoint requires requests to be authenticated.

Ticket #45098

Themes

A minimal wp/v2/themes themes endpoint has been introduced to inform the new block-based editor of the features that the active theme supports. This allows the correct panels, features, and UI elements to be shown or hidden for the user.

This will currently only return data about the active theme. This endpoint must also be accompanied by the status parameter with a value of active. For example: wp/v2/themes?status=active

The current data included in the response is:

  • A list of post formats supported.
  • Post thumbnail support details.
  • Whether responsive embeds are supported.

In the future the themes endpoint can be expanded, but this was the minimum required information for the new block editor to have all the data it needs to work correctly.

Note: This endpoint requires requests to be authenticated.

Ticket #45016

Additional Changes of Note

In addition to the new endpoints, there are a number of changes to REST API responses developers should be aware of.

  • All custom taxonomies must have show_in_rest set to true in order to appear in the new editor.
  • A new function wp_is_json_request() has been added to determine if the request is expecting a JSON response, and if so, silence PHP warnings and errors. [43730]
  • In order for clients to present permalink previews, the REST API must share the computed results of get_sample_permalink(). These values are now exposed as permalink_template and generated_slug for public, viewable post types, but only for context=edit. [43720]
  • Any fields registered with register_rest_field() now respect the ?_fields= filter parameter in the request URL. [43736]
  • Users with read_private_posts capability can now query for private posts on the posts endpoint. [43694]
  • The unfiltered_html capability is now declared using JSON Hyper Schema targetSchema. [43682]
  • block_version value is added to the post object to denote whether post contains blocks and of what version. At this point there is only one version, but if the block format has backwards compatibility breaking changes in the future, we can increment this value as needed. [43770]
  • New rest_after_* action hooks have been added that fire after all write operations have completed. [42864]

View all REST API tickets in the 5.0 release milestone »

#5-0, #dev-notes