New and modified REST API endpoints in WordPress 5.5

In WordPress 5.5, a handful of entirely new 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/. endpoints have been introduced and several others will see new features or enhancements. Let’s look at a breakdown of these changes.

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. Types

In [48173] REST API endpoints were introduced to return all of the block types registered on the server.

  • GET /wp/v2/block-types will return all registered block types.
  • GET /wp/v2/block-types/core will return all blocks within the core namespace.
  • GET /wp/v2/block-types/core/quote will return the definition specifically for the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. quote block.

This endpoint is accessible to users that have edit permission for any post type that is included in the REST API. In other words, if the user can edit posts in the Block Editor, they can access the block types endpoint.

Response Format

The response format for this endpoint closely follows the Block Type Registration RFC. The JSON Schema documents the full response type. The following is an example of that in practice for the core/quote block.

{
  "attributes": {
    "value": {
      "type": "string",
      "source": "html",
      "selector": "blockquote",
      "multiline": "p",
      "default": ""
    },
    "citation": {
      "type": "string",
      "source": "html",
      "selector": "cite",
      "default": ""
    },
    "align": {
      "type": "string"
    }
  },
  "is_dynamic": false,
  "name": "core/quote",
  "title": "",
  "description": "",
  "icon": null,
  "category": "text",
  "keywords": [],
  "parent": null,
  "provides_context": [],
  "uses_context": [],
  "supports": {
    "anchor": true
  },
  "styles": [],
  "textdomain": null,
  "example": null,
  "editor_script": null,
  "script": null,
  "editor_style": null,
  "style": null
}

For more information, refer to the relevant ticketticket Created for both bug reports and feature development on the bug tracker. on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. (#48173).

Plugins

In [48242] REST API endpoints were introduced for managing plugins. These endpoints facilitate the Block Directory Inserter feature in the block editor.

  • GET /wp/v2/plugins will return a list of all plugins installed on a site.
  • GET /wp/v2/plugins/akismet/akismet will return information about the installed Akismet 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. The first akismet refers to the plugin’s folder, the second akismet is the main plugin file without the .php file extension.
  • POST /wp/v2/plugins { slug: "akismet" } installs the plugin with the slug aksimet from the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ plugin directory. The endpoint does not support uploading a plugin zip.
  • PUT /wp/v2/plugins/akismet/akismet { status: "active" } activates the selected plugin. The status can be set to network-active to networknetwork (versus site, blog) activate the plugin on Multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site. To deactivate the plugin set the status to inactive. There is not a separate network-inactive status, inactive will perform a network deactivation if the plugin was network activated.
  • DELETE /wp/v2/plugins/akismet/akismet uninstalls the selected plugin. The plugin must be inactive before deleting it.

The endpoint is accessible to authenticated users with the activate_plugins capability. Specific actions have their own additional permission checks. For instance, the install_plugins capability is required to install new plugins.

Response Format

The JSON Schema for the endpoint documents the full response type. The following is an example for the Akismet plugin.

{
  "plugin": "akismet/akismet",
  "status": "inactive",
  "name": "Akismet Anti-Spam",
  "plugin_uri": "https://akismet.com/",
  "author": "Automattic",
  "author_uri": "https://automattic.com/wordpress-plugins/",
  "description": {
    "raw": "Used by millions, Akismet is quite possibly the best way in the world to <strong>protect your blog from spam</strong>. It keeps your site protected even while you sleep. To get started: activate the Akismet plugin and then go to your Akismet Settings page to set up your API key.",
    "rendered": "Used by millions, Akismet is quite possibly the best way in the world to <strong>protect your blog from spam</strong>. It keeps your site protected even while you sleep. To get started: activate the Akismet plugin and then go to your Akismet Settings page to set up your API key. <cite>By <a href=\"https://automattic.com/wordpress-plugins/\">Automattic</a>.</cite>"
  },
  "version": "4.1.6",
  "network_only": false,
  "requires_wp": "",
  "requires_php": "",
  "text_domain": "akismet"
}

For more information, refer to the relevant ticket on Trac (#50321).

Block Directory

The [48242] changeset also introduced an endpoint for searching the WordPress.org block directory.

GET /wp/v2/block-directory/search?term=starscape searches for blocks that match the term starscape.

This endpoint requires both the activate_plugins and install_plugins capabilities.

Response Format

The JSON Schema for the endpoint documents the full response type. The following is an example for the Starscape block.

{
  "name": "a8c/starscape",
  "title": "Starscape Block",
  "description": "Everything was made of collapsing stars, we are all made of star stuff. Now we also can create content in WordPress with stars in motion. Requirements As this is part...",
  "id": "starscape",
  "rating": 0,
  "rating_count": 0,
  "active_installs": 10,
  "author_block_rating": 0,
  "author_block_count": 1,
  "author": "Automattic",
  "icon": "https://ps.w.org/starscape/assets/icon.svg?rev=2232475",
  "assets": [
    "https://ps.w.org/starscape/tags/1.0.2/index.js?v=1591313160",
    "https://ps.w.org/starscape/tags/1.0.2/editor.css?v=1591313160",
    "https://ps.w.org/starscape/tags/1.0.2/style.css?v=1591313160"
  ],
  "last_updated": "2020-06-04T23:26:00",
  "humanized_updated": "1 month ago",
  "_links": {
    "wp:install-plugin": [
      {
        "href": "http://trunk.test/wp-json/wp/v2/plugins?slug=starscape"
      }
    ]
  }
}

For more information, refer to the relevant ticket on Trac (#50321).

Image Editing

In [48291] an endpoint was introduced for editing image attachments in the media library. This facilitates the inline image editing feature in the block editor.

POST /wp/v2/media/5/edit edits the image with id 5. This rotates the image 90 degrees, and then zooms the image to 80% of its original height and width into the top-left corner.

{
  "x": 0,
  "y": 0,
  "width": 80,
  "height": 80,
  "rotate": 90
}

Notes: width and height only supports percentage values. x & y specify the crop starting point.

This endpoint requires permission to edit the original attachment as well as the upload_files capability. The endpoint returns the newly created attachment.

For more information, refer to the relevant ticket on Trac (#44405).

Block Renderer

Every block has a different set of attributes. These attributes are specified as 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. Schema object. Previously, every block registered its own block renderer route using its attributes for the schema. This allowed for the attributes to be validated using the built in endpoint validation rules.

However, this approach had the unfortunate side effect of creating a large number of nearly identical REST API routes (one for each dynamic block). Each registered route has a performance impact. As the number of server side blocks goes up, this becomes more and more of an issue.

In [48069], the block renderer route was changed to register a single block renderer route and dynamically validate the attributes based on the selected block. This is an internal only change, consumers of the block renderer endpoint shouldn’t notice any changes. The same request format continues to work.

However, this means the attributes schema for a block can no longer be fetched by making an OPTIONS request to the block renderer endpoint. The new block types endpoint should be used instead.

In [47756] support for the POST request method was added to the block renderer. This allows a block to be rendered that has attributes larger than would be allowed in the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org.

For more information, refer to the tickets on Trac (#49680 and #48079).

Themes

In [47921], support for returning the majority of a theme’s 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. information from its public style.css file was added to the /wp/v2/themes endpoint. Previously, only the theme’s supported features were returned.

For example, Twenty Twenty now produces the following response:

{
  "stylesheet": "twentytwenty",
  "template": "twentytwenty",
  "requires_php": "5.2.4",
  "requires_wp": "4.7",
  "textdomain": "twentytwenty",
  "version": "1.4",
  "screenshot": "http://trunk.test/wp-content/themes/twentytwenty/screenshot.png",
  "author": {
    "raw": "the WordPress team",
    "rendered": "<a href=\"https://wordpress.org/\">the WordPress team</a>"
  },
  "author_uri": {
    "raw": "https://wordpress.org/",
    "rendered": "https://wordpress.org/"
  },
  "description": {
    "raw": "Our default theme for 2020 is designed to take full advantage of the flexibility of the block editor. ",
    "rendered": "Our default theme for 2020 is designed to take full advantage of the flexibility of the block editor."
  },
  "name": {
    "raw": "Twenty Twenty",
    "rendered": "Twenty Twenty"
  },
  "tags": {
    "raw": [
      "blog",
      "one-column",
      "custom-background",
      "custom-colors",
      "custom-logo",
      "custom-menu"
    ],
    "rendered": "blog, one-column, custom-background, custom-colors, custom-logo, custom-menu"
  },
  "theme_uri": {
    "raw": "https://wordpress.org/themes/twentytwenty/",
    "rendered": "https://wordpress.org/themes/twentytwenty/"
  },
  "theme_supports": {}
}

Currently, themes can declare support for a given feature by using add_theme_support(). In [48171], the register_theme_feature 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. was introduced that allows WordPress Core and plugins to declare a list of available features that themes can support.

The REST API uses this to expose a theme’s supported features if the feature has been registered with show_in_rest set to true.

As a reminder, the themes endpoint is available to any users who can edit a post type that is visible in the REST API. In other words, if a user can use the Block Editor, they can access this information.

For more information, refer to the relevant tickets on Trac (#49906 and #49406).

Props @desrosj and @justinahinon for reviewing.

#5-5, #dev-notes, #rest-api