Understanding the WordPress REST API
The WordPress REST API allows developers to interact with a WordPress site using JSON, turning a traditional CMS into a headless backend or a data source for external applications. By accessing endpoints via the wp-json namespace, you can create, update, delete, and retrieve content without needing to write complex PHP queries or rely solely on the WordPress admin dashboard.
For many developers, the API is the primary way to build decoupled frontends using frameworks like React or Vue, or to synchronize data between a WordPress site and a mobile app. Knowing which endpoints to use prevents unnecessary server load and reduces the amount of custom code needed to achieve common tasks.
The Core Content Endpoints
Most development work centers around the wp/v2 namespace, which contains the most frequently used resources. These endpoints handle the primary data structures of any WordPress installation.
Posts and Pages
The /wp/v2/posts and /wp/v2/pages endpoints are the most common starting points. A GET request to these URLs returns a list of posts or pages. However, requesting the entire list is rarely practical for production sites due to pagination.
Developers can use the per_page parameter to limit the number of results and page to navigate through the set. To retrieve a specific piece of content, appending the ID to the path (e.g., /wp/v2/posts/123) provides the full object for that single entry. These endpoints support filtering by author, category, or date, which makes them ideal for building custom archive pages.
Categories and Tags
Taxonomies are handled via /wp/v2/categories and /wp/v2/tags. These are useful for building navigation menus or filter sidebars in a headless setup. Because these endpoints return the taxonomy terms and their associated counts, you can dynamically generate a list of the most popular topics on a site without hardcoding IDs into your frontend.
Users and Profiles
The /wp/v2/users endpoint provides information about the people who contribute to the site. While public profiles are accessible, sensitive user data is protected. Attempting to access private user information without a valid authentication token will result in a 401 Unauthorized error. This endpoint is particularly useful for creating author bio sections or user directories.
Managing Media and Attachments
The /wp/v2/media endpoint governs all files uploaded to the WordPress Media Library. Unlike posts, media objects contain specific metadata about the file, such as MIME type, alt text, and various image sizes generated by WordPress.
When fetching media, the API returns a source_url for the original file and a media_details object. The latter is critical for responsive design, as it contains the URLs for thumbnail, medium, and large versions of the image. This allows developers to load the smallest appropriate image for the user’s device, improving page load speeds.
Administrative and Site-Wide Endpoints
Beyond content, developers often need information about the site’s general configuration or status.
Site Settings
The /wp/v2/settings endpoint allows for the retrieval and modification of global site settings. This includes the site title, tagline, and administration email. Modifying these settings via the API requires high-level administrative privileges, making it a common target for security plugins that disable certain REST endpoints to harden the site.
The Index Endpoint
If you are unsure which endpoints are available on a specific installation, a GET request to the root /wp-json/ path returns a massive JSON object. This index lists every available route, the required permissions for each, and the supported methods (GET, POST, PUT, DELETE). It serves as a live map of the API’s current state, including endpoints added by third-party plugins.
Handling Authentication and Permissions
Public GET requests are straightforward, but any action that modifies data (POST, PUT, DELETE) requires authentication. WordPress does not use simple API keys by default; it relies on more robust methods to ensure security.
Application Passwords
Introduced in WordPress 5.6, Application Passwords provide a way to authenticate external requests without using the main user password. A developer can generate a unique password for a specific application in the user profile. This password is sent via Basic Auth in the request header. It is a practical solution for simple scripts or internal tools, though it should be used with caution on sites without HTTPS.
JWT Authentication
For more complex applications, especially those with many users, JSON Web Tokens (JWT) are the standard. Since WordPress does not include JWT natively, developers typically use plugins to implement it. This method is more secure for client-side applications because it doesn’t require sending user credentials with every request; instead, it uses a signed token that expires after a set period.
Practical Limitations and Performance
While the REST API is flexible, it is not without constraints. Every API call triggers a WordPress bootstrap process, which means the server must load the core files, active plugins, and the theme before responding. On sites with many plugins, this can lead to slower response times compared to a dedicated Node.js or Go backend.
To mitigate this, developers should focus on minimizing the number of requests. The _embed parameter is an essential tool here. By adding ?_embed to a request, WordPress includes linked data (like the author’s name or featured image) in the primary response. This prevents the “N+1 query problem,” where a developer would otherwise have to make one request for a list of posts and then separate requests for every single author associated with those posts.
Frequently Asked Questions (FAQs)
Can I create my own custom wp-json endpoints?
Yes, you can use the register_rest_route function in a custom plugin or your theme’s functions.php file. This allows you to define your own namespaces and callbacks to return specific data from the database that the default endpoints do not provide.
Why am I getting a 404 error when accessing wp-json?
This is usually caused by permalinks being set to “Plain.” The REST API requires a pretty permalink structure to function correctly. Changing the permalink settings to “Post name” in the WordPress dashboard typically resolves this issue.
How can I protect my REST API from public access?
You can use a filter on rest_authentication_errors to check if a user is authenticated before allowing access to specific endpoints. Some security plugins also provide a toggle to disable the REST API for non-logged-in users entirely.
Does the REST API support custom post types?
Custom post types are not exposed to the API by default. When registering a custom post type using register_post_type, you must set the show_in_rest argument to true for it to appear in the wp-json directory.
Is it better to use GraphQL or the REST API for WordPress?
The REST API is built-in and easier to set up for simple projects. GraphQL, usually added via the WPGraphQL plugin, is more efficient for complex frontends because it allows the client to request exactly the fields they need in a single request, reducing payload size.
Can I update a post’s status using the API?
Yes, by sending a POST request to /wp/v2/posts/{id} with the status parameter set to “publish”, “draft”, or “private”. This requires the requesting user to have the appropriate permissions to edit that specific post.
