Skip to main content

Using the WordPress REST API

Learn how to use the WordPress REST API at Seravo. This guide covers nginx caching, using the ?nocache parameter, setting up Application Passwords, and troubleshooting common errors like 401, 403, 404, and 429 rate limiting.

Updated over a week ago

The WordPress REST API is an interface that allows you to interact with your site's data (such as posts, pages, and users) in JSON format. It is a cornerstone of modern WordPress development, whether you are using the Block Editor (Gutenberg), external integrations, or headless solutions.

By default, your site's REST API is available at: https://example.com/wp-json/

Caching and the REST API

Seravo uses a high-performance nginx-based HTTP cache. This affects REST API requests in the following ways:

Caching

By default, API GET requests are cached to improve performance and reduce server load.

Bypassing the Cache

To ensure you are retrieving the most recent data directly from the database, add the ?nocache=1 parameter to your request. For example: https://example.com/wp-json/wp/v2/posts?nocache=1. This is highly recommended during development or for dynamic applications.

Updates and Purging

Please note that updating a post in WordPress might not automatically purge the REST API cache. If necessary, you can manually clear the cache via the command line using wp-purge-cache or through the Seravo Plugin in the WordPress dashboard.

Verifying Cache Status

You can verify if a response is served from the cache by inspecting the HTTP response headers using a tool like curl:

curl -I https://example.com/wp-json/wp/v2/posts/123

Key headers to check:

  • x-proxy-cache: A value of HIT means the response was served from the cache. MISS or BYPASS (e.g., when using ?nocache=1) indicates the request went directly to WordPress.

  • Cache-Control: Defines how the response should be cached. Values like no-cache, no-store, or max-age=0 prevent the response from being stored in the cache.

  • Pragma: A legacy header (often no-cache) used for similar purposes as Cache-Control. If set, it may prevent caching.

Note: If you manually set these headers in your theme or plugin (e.g., using PHP's header() function), they will dictate how Seravo's nginx cache handles the API responses.

Restricting API Access and Security

By default, many API endpoints are public. If your site contains sensitive information, you can restrict access via code or plugins. However, keep in mind that many core WordPress features rely on the REST API to function properly.

Authentication

To perform actions that modify data (such as creating a new post), requests must be authenticated. The recommended method is using Application Passwords.

How to create an Application Password:

  1. Log in to your WordPress dashboard and go to Users > Profile.

  2. Scroll down to the Application Passwords section.

  3. Enter a name for the password (e.g., "Dev-Test") and click Add New Application Password.

  4. Securely save the generated password (xxxx xxxx xxxx xxxx).

Include the password in your request using Basic Auth: -u "username:xxxx xxxx xxxx xxxx"

Troubleshooting

401 Unauthorized

The Application Password or username is incorrect, or the Authorization header is not reaching the server. Ensure you are using your actual username (not an email address) and the recently generated Application Password.

404 Not Found

Ensure that your WordPress Permalink structure is set to something other than Plain. The standard /wp-json/ path requires a path-based permalink structure. If you cannot change the permalinks, you must call the API using the format /?rest_route=/.

403 Forbidden

The request was blocked due to insufficient permissions or a security filter.

  • Permissions: Ensure the user has the required capabilities for the action (e.g., editing posts).

  • Web Application Firewall (WAF): Seravo's WAF may block requests that it perceives as malicious. If you encounter this error without an obvious cause, please contact our customer support.

429 Too Many Requests

You have made too many requests in a short period. Automatic rate limiting is in place to protect the site from being overloaded. If your integration requires high request volumes, contact our customer support to review your limits.

Further Reading

Need help?

Contact our customer service by sending a message to [email protected].

Related Articles
WordPress Rewrites
Headless WordPress
Logs Available for the Site
List of Commands and Tools
WordPress and XML-RPC
Did this answer your question?