Guide to the WordPress REST API

What is the WordPress REST API

The WordPress ecosystem REST API is an interface that lets external applications communicate with a WordPress site via HTTP requests. Instead of accessing content through the WordPress frontend or admin panel, the REST API lets you read, create, update, and delete content programmatically, using standard HTTP methods (GET, POST, PUT, DELETE) and the JSON format for data exchange.

The REST API has been built into WordPress since version 4.7 (December 2016) and represents the modern way to interact with WordPress. It's used for mobile apps that display WordPress content, JavaScript frontends (React, Vue, Angular) that use WordPress as the backend, integrations with external services, and content management automation. The Gutenberg editor, the standard WordPress editor since version 5.0, intensively uses the REST API for all content operations. If you're just starting, see our WordPress installation guide.

REST API basics

Endpoints and routes

The WordPress REST API is available on your site under the /wp-json/ path. Using a browser or a tool like cURL or Postman, you can access the API. For example, a GET request to /wp-json/wp/v2/posts returns a list of posts in JSON format, /wp-json/wp/v2/pages returns pages, /wp-json/wp/v2/categories returns categories, /wp-json/wp/v2/users returns users, /wp-json/wp/v2/media returns media files, and /wp-json/wp/v2/comments returns comments. Each of these endpoints supports different HTTP methods for different operations - GET for reading, POST for creating, PUT/PATCH for updating, and DELETE for deletion.

Query parameters

The REST API supports numerous parameters for filtering and paginating results. The per_page parameter controls the number of results per page (default 10, max 100), page specifies the result page for pagination, search searches content by keyword, orderby defines the sort field (date, title, id), order defines the sort direction (asc or desc), and categories and tags filter by category or tag. For example, the request /wp-json/wp/v2/posts?per_page=5&categories=3&orderby=date&order=desc returns the 5 most recent posts from the category with ID 3.

Response structure

The API returns data in JSON format. Each post object contains id (unique identifier), title with a rendered property (title with HTML formatting), content with a rendered property (post content), excerpt with a rendered property (excerpt), date (publish date in ISO 8601 format), slug (URL-friendly title), status (publish, draft, pending), author (author ID), categories, and tags (arrays of IDs). HTTP response headers contain useful metadata: X-WP-Total (total number of items) and X-WP-TotalPages (total number of pages).

Authentication

Public vs protected endpoints

Some endpoints are publicly available without authentication - reading published posts, pages, categories, and tags. Operations that modify data (create, update, delete) and access to private data require authentication. The WordPress REST API supports several authentication methods depending on the usage context.

Application Passwords

Since WordPress 5.6, Application Passwords are built into core and represent the simplest way to authenticate external applications. You create an Application Password for a user in Users → Profile → Application Passwords. The generated password is used with HTTP Basic Authentication - you send the username and application password in the Authorization header of every request. Application Passwords have the advantage that they can be revoked individually without changing the user's main password.

JWT authentication

JSON Web Token (JWT) is a popular authentication method in single-page applications and mobile apps. WordPress doesn't have built-in JWT support, but plugins like JWT Authentication for WP REST API or Simple JWT Login add this functionality. The client sends username and password to the token endpoint, gets a JWT token, and then sends it in the Authorization header as a Bearer token with every request. JWT tokens have a limited lifetime and can be refreshed without resending the password.

OAuth 2.0

OAuth 2.0 is the industry standard for authorization that lets third parties access resources without sharing passwords. WordPress supports OAuth through the OAuth Server plugin. OAuth is ideal for applications that access WordPress content on behalf of a user - the user authorizes the application through the WordPress login page, the application receives an access token, and uses it for API calls. This is the most secure method for production applications.

Creating custom endpoints

Register REST Route

WordPress lets you create custom API endpoints for the specific needs of your application. Use the register_rest_route() function in the rest_api_init hook. You define the namespace (e.g., myplugin/v1), the route (e.g., /featured-posts), the HTTP method (GET, POST), a callback function that returns data, and an optional permission_callback function for access control. Custom endpoints are useful for data that requires complex queries, aggregations, or transformations the standard endpoints don't support.

Permission Callback

The permission callback function controls who can access the endpoint. For public endpoints, use __return_true. For protected endpoints, check user permissions using the current_user_can() function. For example, an endpoint for creating posts should check current_user_can('publish_posts'). Never leave write endpoints without a permission callback because that opens the site to abuse.

Parameter validation and sanitization

Custom endpoints should define arguments with validation and sanitization. For every parameter you define required (whether it's mandatory), type (string, integer, boolean), validate_callback (function that checks the validity of the value), and sanitize_callback (function that cleans the value before use). WordPress offers built-in sanitize functions like sanitize_text_field(), absint(), and sanitize_email(). Proper validation prevents unexpected errors and security vulnerabilities.

Headless WordPress

The headless CMS concept

Headless WordPress is an architecture where WordPress is used only as a backend (CMS) for content management, while the frontend display runs in a completely separate application. The WordPress REST API serves as the bridge between backend and frontend. The frontend can be built in React, Vue.js, Next.js, Nuxt, Angular, or any other framework. The advantages are full frontend control, better performance (static pages instead of WordPress PHP rendering), the ability to use the same content on a website, mobile app, and other platforms, and modern development experience (hot reloading, component-based architecture).

Next.js and WordPress

The combination of Next.js and WordPress is one of the most popular headless implementations. Next.js provides server-side rendering (SSR), static site generation (SSG), and incremental static regeneration (ISR), resulting in extremely fast sites. Content is fetched from the WordPress REST API during build (for SSG) or on demand (for SSR). The Next.js Image component automatically optimizes images, and the routing system maps WordPress slugs to pages. Many large sites use this combination for blog sections while the rest of the site uses custom components.

Headless challenges

Headless WordPress isn't without challenges. You've lost WordPress themes and the visual customizer - everything has to be coded in the frontend framework. Plugins that generate frontend output (contact forms, galleries, page builders) don't work in headless mode. Preview functionality requires additional configuration. SEO plugins like Yoast generate meta data but the frontend has to fetch and properly display it. Comments, search, and pagination must be implemented on the frontend using API calls. The headless approach requires a team with frontend development experience.

REST API security

Restricting access

By default, the WordPress REST API is publicly available and reveals information about users, posts, and site structure. For a site that doesn't use the API, consider restricting access. You can disable the REST API for unauthenticated users using the rest_authentication_errors filter, block specific endpoints (especially /wp/v2/users which reveals usernames), or use a plugin like Disable WP REST API for selective disabling. Never block the REST API entirely if you use the Gutenberg editor because it depends on the API.

Rate Limiting

A REST API without rate limiting can be abused for brute force attacks, content scraping, or DDoS. Implement rate limiting at the web server level (Nginx limit_req module, Apache mod_ratelimit) or using WAF rules. Cloudflare Rate Limiting is a simple solution - limit the /wp-json/ endpoint to a reasonable number of requests per minute (e.g., 60 for authenticated, 30 for unauthenticated users).

Useful tools for working with the REST API

• Postman: A graphical tool for testing API calls with support for all HTTP methods, authentication, and request collections.
• cURL: A command-line tool for HTTP requests - ideal for quick testing and scripting.
• Insomnia: A modern alternative to Postman with a clean interface and GraphQL support.
• WP-CLI: The WordPress command-line tool that internally uses the REST API and lets you manage the site from the terminal.
• Thunder Client: A VS Code extension for testing APIs directly from the editor.

Conclusion

The WordPress REST API opens new possibilities for using WordPress beyond the traditional blog or site. Whether you're building a mobile app, JavaScript frontend, or integrating WordPress with other systems, the REST API provides a standardized and documented way to access content. For headless projects, the combination of WordPress and a modern frontend framework like Next.js offers the best of both worlds - simple content management and top performance. At BeoHosting, all WordPress hosting plans support the REST API with optimized PHP and MySQL configurations for faster API responses.