William Earnhardt 4:21 pm on December 6, 2018
Tags: ,   

The REST API in WordPress 5.0

WordPress 5.0 contains several additions to the 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/. that help provide the new blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. based editor with all the data it needs. Let’s talk about them!

New CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. 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 revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision., 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.

Ticketticket Created for both bug reports and feature development on the bug tracker. #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 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 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 UIUI User interface 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 JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. response, and if so, silence PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org. [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]
  • A 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