WordPress REST API

This document describes how your usage of the WordPress REST API can be structured to ensure your application and your WordPress installation are as performant and stable as possible. It may be helpful to first review the following definitions of terms used on this page:

Front-end API requests: WordPress REST API requests used to generate the front end of the site in some application, e.g. requests made by a NodeJS app which is generating the front end, or from a mobile application, etc.

WordPress REST API responses: the response of the WordPress REST API to requests.

General guidelines

Our guidelines and requirements around front-end API requests are as follows:

• 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 VIP Go Varnish cache.

Our guidelines and requirements around WordPress REST API responses are similar to our requirements for WordPress themes. Please bear the following in mind:

• 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 VIP Go; VIP Go runs a Varnish caching layer. API requests from your front end application should aim to hit this cache to serve the responses efficiently and from a location nearer your users.
• WordPress REST API responses to front-end API requests should never cause writes; as traffic increases, database writes will easily cause issues with site stability and uptime.

For a significant utilization of the WordPress REST API (e.g. replacing the front end of your site with a Node application or a high usage mobile application), we will ask you to talk over the following points with us:

• What is the caching strategy for your application: what are you caching, how are you caching, 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 your application make when the caches are cold? What requests will be made when the caches are warm?
• How fast are your API endpoints in responding to common requests used to generate popular views in your application?
• What is your test plan for your use of the REST API?
• What is your rollout plan for your use of the REST API (including a rollback plan)?

Location

To reduce complexity and avoid compatibility issues, we strongly recommend you do not change the rest_url_prefix from wp-json (i.e. do not move the WordPress REST API endpoints from http://example.com/wp-json/). This can cause issues with various VIP services which utilize the REST API on each VIP Go site.

Caching

By default, VIP Go will cache most REST API endpoints for 1 minute. We strongly recommend that your site does not change this to use PURGEs.

If you want to adjust the TTL for REST responses, you can use the 'wpcom_vip_rest_read_response_ttl' filter:

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 );