How To Use The WordPress REST API
What is an API (Application Programming Interface)?
An API can be defined simply as a set of code that makes it possible for a system to interact with other systems. It is a client and server communication protocol whose aim is to simplify the building of a client side software. A good example of an API is the Google Maps API that allows a WordPress website to interface with Google Maps.
However, these systems do not necessarily have to be completely separate. For example, WordPress has a number of other APIs working with shortcodes, plugins, and settings. Theme developers use these APIs to meet different requirements.
WordPress REST (Representational State Transfer) API
WordPress REST API is an interface used by developers to gain access to WordPress from outside the WordPress installation itself. The WordPress REST API can be used to create interactive apps and websites.
The difference between the REST APIs and the other APIs is the REST part, which allows WordPress to interact with systems outside the WordPress installation itself.
To understand how the WordPress REST API works, there are a few things that you need to know. They include;
- Key concepts and terms.
- Useful REST API endpoints.
- REST API authentication.
Key Concepts and Terms
The key concepts and terms that you need to understand include;
- Routes and Endpoints: A route is the URL that is mapped to different HTTP methods while an endpoint is the connection between a route and an HTTP method.
- Responses: A response provides the requested data or returns an error telling you what could have gone wrong.
- Requests: A request is used to retrieve and store information for the current request.
- Controller Classes: This is where the REST API moving parts are managed.
- Schema: The schema provides a list of all input parameters and properties that can be accepted and returned by the REST API.
Useful REST API Endpoints
The REST API endpoint can be defined as one end of the communication channel. When the REST API is interacting with another system, the touchpoints of the communication between the two systems is considered to be an endpoint. Each of these REST API endpoints serve as the location from which APIs gain access to all the resources that they need to complete their function.
REST API Authentication
WordPress observes a high level of security. This means that it will need to know who you are before you can make any changes no matter where you are sending your requests from. You can have a look at the REST API Handbook to understand the basics of REST API authentication.
Using the WordPress REST API
1. Accessing the REST API
You can gain access to the WordPress REST API using any application that can submit HTTP requests such as the WP-CLI or even your browser. To access the CLI, open Command Prompt in Windows or Terminal on a Mac or in Linux.
If you are accessing a remote site via the CLI, you will need to SSH to your server. For those accessing a local site, make sure that you are using the correct directory structure from the command line.
For example, to use the REST API to get a list of posts in your WordPress website, simply add /wp-json/wp/v2/posts to the end of your WordPress site URL. This generates a list of posts in JSON format.
2. Fetching Specific Posts using REST API
There are a number of arguments you can use to return specific posts. For example, the example above returned the list of posts you have on your WordPress website. To get a specific post, you will have to use its ID in this format; /wp-json/wp/v2/posts/post-ID.
Other important arguments to note include per_page that allows you to specify the number of results you want to return, order that allows you to specify the order of the returned results and categories that returns posts in a specific category.
3. Adding Metadata to a Post
You will need to be authenticated to be able to add metadata to a post using the WordPress REST API. To add metadata, the REST API uses the POST command. For example, /wp-json/wp/v2/posts/post-ID/meta?value=newmetadata
Metadata and their use are described in the Developer Manual: Metadata and Lineage.
WordPress REST API is very resourceful and can help you achieve a lot of things to extend the functionality of your website. There is much more that you can learn about the REST API to make sure that you use it extensively to meet the requirements of your website.