Skip to content

WordPress REST API

The WordPress REST API provides an interface for applications to interact with a 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 WordPress.org 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.
  • Avoid changing the rest_url_prefix fromwp-json (i.e. do not move the WordPress REST API endpoints from http://example.com/wp-json/). Doing so can add unnecessary complexity and cause compatibility issues with various VIP services that utilize the REST API.

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 applications. Examples include requests made by a mobile application or requests made by a Node.js application that generates a site’s front end.

Guidelines and requirements for front-end API requests:

  • The front-end application should handle unexpected responses to front-end API requests robustly and gracefully. For example, network conditions preventing the request from reaching the API or bugs in the API code could cause unexpected results. Front-end applications could accommodate this eventuality by serving stale content from an object cache within the front-end application, showing an appropriate error page, or backing off in request frequency to the API endpoint.
  • Authenticated requests bypass the page cache. Only authenticated front-end users should generate authenticated front-end API requests. Authenticating any proportion of front-end API requests can cause site stability and uptime issues.

REST API response guidelines

  • WordPress REST API responses should be fast and performant. API stability will be strongly correlated to how swiftly API endpoints can respond to requests, especially for authenticated requests, which will not benefit from page caching. Use traditional WordPress performance optimization techniques to achieve fast API responses, such as using object caching to reduce repetitive expensive operations, and avoiding external HTTP requests.
  • API requests from a front-end application should aim to hit the page cache to serve the responses efficiently 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

By default, REST API endpoints are cached 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.

To optimize performance, avoid lowering 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

Structure WordPress REST API usage to ensure that an application and a WordPress installation are as performant and stable as possible. Consider the following questions 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 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 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 REST API (including a rollback plan)?

Last updated: September 05, 2023

Relevant to

  • WordPress