Skip to content

WordPress REST API

The WordPress REST API provides an interface for applications to interact with your WordPress site by sending and receiving data as JSON (JavaScript Object Notation) objects.

To learn more about working with the WordPress REST API, refer to the REST API Handbook.

Requirements

  • For the WordPress REST API to work as expected, pretty permalinks must be enabled on the WordPress site. If pretty permalinks are not enabled, attempts to load a site’s REST API endpoint will load the site’s homepage instead.
  • It is strongly recommend not to change the rest_url_prefix from wp-json (i.e. do not move the WordPress REST API endpoints from http://example.com/wp-json/). Doing so can add unnecessary complexity cause compatibility issues with various VIP services which utilize the REST API on each VIP site.

Front-end API requests

Front-end API requests are requests to a WordPress REST API that are used to generate the front end of a site in some application (e.g., requests made by a Node.js application which is generating the front end, or requests made by a mobile application).

Guidelines and requirements for front-end API requests:

  • The front-end application should handle unexpected responses to front-end API requests robustly and gracefully; when the front end application receives an unexpected result (e.g. because network conditions prevent the request reaching the API or because of a bug in the API code) it should accommodate this eventuality (e.g. serve up stale content from an object cache within the front end application, show an appropriate error page, back off in request frequency to the API endpoint, etc.).
  • Only authenticated front-end users should generate authenticated front-end API requests. Authenticating any proportion of front-end API requests can easily cause issues with site stability and uptime. Authenticated requests bypass the page cache.

WordPress REST API responses

Guidelines and requirements for the response of the WordPress REST API to requests:

  • WordPress REST API responses should be fast and performant; your API stability will be strongly correlated to how swiftly your API endpoints can respond to requests (especially for any authenticated requests which will not benefit from Varnish caching). Fast API responses can be achieved using traditional WordPress performance optimization techniques, such as using object caching to reduce repetitive expensive operations, avoiding external HTTP requests, etc.
  • WordPress REST API responses to front-end API requests should be cached by the page cache. API requests from a front end application should aim to hit this cache to serve the responses efficiently and from an edge cache server closest to the user making the request.
  • WordPress REST API responses to front-end API requests should never cause writes; as traffic increases, database writes can negatively impact site stability and uptime.

Caching

REST API endpoints are cached by default for 1 minute. The wpcom_vip_rest_read_response_ttl filter can be used to modify the Time To Live (TTL) of the cached REST response, but for performance reason it is strongly recommended not to lower the TTL below 1 minute.

This code example demonstrates how to use the wpcom_vip_rest_read_response_ttl filter to increase the TTL for a REST response to five minutes:

add_filter( 'wpcom_vip_rest_read_response_ttl', function( $ttl, $response, $rest_server, $request ) {
    // Cache REST API GET requests for 5 minutes.
    return MINUTE_IN_SECONDS * 5;
}, 10, 4 );

Considerations

Usage of the WordPress REST API should be structured to ensure that an application and a WordPress installation are as performant and stable as possible. The following questions should be considered for applications that make significant usage of the WordPress REST API (e.g., replacing the front end of a site with a Node.js application, or a high usage mobile application):

  • What is the caching strategy for an application? What is being cached, how is it being cached, how long are the caches held for, and how will the caches be cleared?
  • Typical profile of requests: For each type of view, what requests will an application make when the caches are cold? What requests will be made when the caches are warm?
  • How fast are the API endpoints in responding to common requests used to generate popular views in an application?
  • What is the test plan for the use of the REST API?
  • What is the rollout plan for the use of the REST API (including a rollback plan)?

Last updated: January 11, 2023