REST API: Using It

The REST API arrived in two steps: the infrastructure (routing, WP_REST_Server, /wp-json/) in 4.4 and the content endpoints of the wp/v2 namespace in 4.7. A route is a path below the API root, such as /wp/v2/lp_book/5, and an endpoint is a route plus an HTTP method: GET reads, POST creates on a collection or updates an item, PUT and PATCH update, DELETE deletes. Routes are grouped in namespaces (wp/v2, wp-site-health/v1, a plugin’s lumen/v1) so that plugins cannot collide with core and can version their API. Every endpoint declares its arguments and a JSON Schema, so an OPTIONS request to any route describes it; responses carry HAL-style links (_links) to related resources; and every request is authorized by the endpoint’s permission check against the capabilities of the user it is authenticated as. Anonymous requests see what an anonymous visitor could see on the site.

The API does not replace the PHP APIs: theme and plugin code in the same request should call WP_Query and get_post_meta() directly. It is for code on the other side of an HTTP connection.

The figure follows one authenticated request through WordPress, from the URL to the JSON response.

A client should not hard-code /wp-json/: the root depends on the permalink settings and may live in a subdirectory. Every front-end page announces it, both as an HTTP header and as a <link> element in the <head>, so a HEAD request on the home page is enough. With "Plain" permalinks there is no /wp-json/ rewrite rule and the header points to /?rest_route=/ instead; that query-string form works on every site, whatever the permalink settings, and is a useful fallback when a server or firewall blocks the /wp-json/ path:

Source: REST API Handbook: Discovery

The root itself (GET /wp-json/) is the index: the site name, URL, gmt_offset and time zone, the namespaces list, an authentication object (core announces application-passwords with the URL of its authorization screen) and every registered route with its methods and arguments. On the test site with lumen-catalog active it listed 143 routes in the namespaces oembed/1.0, wp/v2, wp-site-health/v1, wp-block-editor/v1 and wp-abilities/v1, plus /batch/v1.

A namespace index (/wp-json/wp/v2) lists only that namespace’s routes. The index is public; it reveals which plugins register routes, but no content. In PHP, build API URLs with rest_url( 'wp/v2/lp_book' ) (or get_rest_url() on Multisite), which honours the permalink setting and the rest_url_prefix filter.

The wp/v2 namespace covers almost everything an editor or administrator can change on screen. The table lists the main routes and what an anonymous request may do; everything else needs a user with the matching capability.

Source: REST API Handbook: Endpoint Reference

A custom post type, taxonomy or meta key only appears in the API when it is registered with show_in_rest; without it the route simply does not exist (404 rest_no_route), and a post type also cannot use the block editor. Older plugin books register custom post types without show_in_rest; see Custom Post Types and Taxonomies and Metadata and Custom Fields. Registered meta appears under meta, and the terms of each REST-enabled taxonomy as an array of term IDs under the taxonomy’s REST base:

Source: REST API Handbook: Posts

Core registers footnotes for post types that support it, hence its presence. Fields such as title and content are objects: rendered is the HTML after filters and blocks have run, and raw (only in the edit context) is what is stored in the database.

The Site Editor routes serve tools that synchronise design between environments, and all of them need an authenticated administrator (scripts that change global styles must run as one). Templates are addressed as <theme>//<slug>: /wp/v2/templates?_fields=id,source listed twentytwentyfive//404, twentytwentyfive//page and the other theme templates with "source":"theme". The id of the user’s global styles post differs per site and is found in the wp:user-global-styles link of /wp/v2/themes?status=active (/wp/v2/global-styles/11 on the test site). The user side of those screens is covered in Site Editor and Global Styles.

Uploading media is a POST to /wp/v2/media of the raw file body (curl --data-binary @file) with Content-Type and Content-Disposition (attachment; filename="lighthouse-ledger.jpg") headers; the 201 response holds the attachment with every generated size under media_details, which a headless front end uses to build its own srcset (see Media Library). A second request with featured_media=10 on /wp/v2/lp_book/5 made it the book cover. Nested _fields such as media_details.width returned no media_details at all on the test site; ask for the whole media_details object.

A few query parameters, sometimes called meta-parameters, are handled by the REST server itself and work on every route, core or custom.

Source: REST API Handbook: Global Parameters

_embed and _fields combine only when the field list includes both _links and _embedded; otherwise the links are filtered out first and nothing is embedded. On the test site, /wp/v2/lp_book/5?_embed&_fields=id,title returned just the id and title, while this request embedded the genre and series terms:

Source: REST API Handbook: Linking and Embedding

lp_book does not support author, so the response has no author link and _embed=author embeds nothing for it; for posts and pages it embeds the author’s public profile. Each embedded request is a separate internal dispatch, so a collection of 100 items with _embed can be expensive: restrict it to the relations the client really displays.

context=edit is what the block editor requests. Anonymous clients get 401 rest_forbidden_context; a user who can edit the item (here lena.catalogue) gets title.raw, content.raw with the block comments, the status and other private fields.

On the test site, a POST to /wp/v2/lp_book/5?_method=PATCH updated the excerpt like a PATCH, and /wp/v2/lp_book/999?_envelope answered 200 with {"body":{"code":"rest_post_invalid_id",...},"status":404,"headers":[]}.

Collections return 10 items by default. per_page accepts 1 to 100, page selects the page and offset skips items. The totals travel in headers, and a Link header carries prev and next URLs:

Source: REST API Handbook: Pagination

A page past the end returns 400 rest_post_invalid_page_number. The 100 limit is deliberate: larger pages hurt the server. A client that needs every item loops over page until X-WP-TotalPages, as the JavaScript client below does. The Allow header lists the methods the current user may use (GET when anonymous; all five for an editor on a book), useful to show or hide edit buttons. Paging through a collection that changes between requests can skip or repeat items; for synchronisation jobs, sort by id or modified and filter with modified_after.

Collection routes accept the filters their controller declares, which an OPTIONS request lists. On /wp/v2/lp_book they include search, after, before, modified_after, modified_before, include, exclude, slug, status, order, orderby, offset, tax_relation and, per taxonomy, lp_genre, lp_genre_exclude, lp_series and lp_series_exclude.

Source: REST API Handbook: Posts, REST API Handbook: Search Results

There is no filter on meta values and no orderby on meta keys: ?orderby=lp_isbn returns 400 rest_invalid_param ("orderby is not one of author, date, …​"), and after filters the post date, not lp_published_on. Lumen Press publishes books with the post date of their release so that core filters work; ordering or filtering on a meta key requires a custom route or the rest_lp_book_query filter (rest_{$this->post_type}_query), see REST API: Extending It. The ?filter[...]= parameter of the pre-4.7 feature plugin, which passed raw WP_Query arguments, was not merged into core; tutorials that use it are outdated.

Reading public content needs no credentials. Everything else needs the request to be authenticated as a user, and then the user’s capabilities decide. Core supports two mechanisms; others come from plugins.

Source: REST API Handbook: Authentication

Errors are JSON objects with a machine-readable code, a translated message and data.status; validation errors add data.params (one message per argument) and data.details. Clients should branch on code and status, never on the message.

Source: REST API Handbook: Using the REST API

The same rule produces 401 or 403 depending on whether anybody is logged in. On the test site:

Source: REST API Handbook: Posts

Authors cannot create pages, and they cannot create books either, because lp_book uses its own edit_lp_books capability, granted only to Administrators, Editors and Catalogue Managers (see Roles and Capabilities API). The settings route requires manage_options for every key. A typo in the route name is a 404, not a 400.

DELETE /wp/v2/lp_book/8 moved the book to the trash ("status":"trash"); ?force=true deletes for good. Terms, users and media (with MEDIA_TRASH off) have no trash and answer 501 rest_trash_not_supported without force=true.

When the editor shows "The response is not a valid JSON response", some code printed output (a PHP notice, a byte-order mark, a security plugin’s HTML page) before the JSON, or a firewall blocked /wp-json/. Request the route with curl to see the raw body, and see Debugging, Site Health and Troubleshooting.

Since 5.6, POST /batch/v1 runs up to 25 write requests (POST, PUT, PATCH, DELETE; GET is not allowed) in one HTTP round trip. Each sub-request has a path (with its own query string), an optional method (default POST), body and headers. The response has status 207 and one entry per sub-request. Only routes that declare allow_batch take part: the core post, attachment, term, user, widget, global styles and font controllers do, and custom routes must opt in (see REST API: Extending It).

Source: Make WordPress Core: REST API Batch Framework in WordPress 5.6

validation decides what happens when one sub-request is invalid:

Batching is not a transaction. Validation happens up front, but a permission or database failure in the middle leaves the earlier requests applied, so clients must read every status. The HTTP status is 207 even when every sub-request failed, and a GET sub-request makes the whole batch fail with 400 rest_invalid_param.

None of the three general WordPress books covers the API from the client’s side (global parameters, pagination headers, batch requests); see Where Older Books and Tutorials Are Outdated.