In the previous parts of the series, we have been looking at what the WP REST API is and how it can help us build better applications using the WordPress back end.
Then, we looked at two different ways to set up authentication on the server for generating authenticated requests. The first is the basic authentication method, which is useful in development environments and allows rapid prototyping as it doesn’t require much time to set up. The advanced method of authentication is OAuth 2.0, which is recommended for production environments as it is much more secure than the basic authentication method.
Now that we’ve learned how to set up authentication, we are ready to generate authenticated requests to unleash the full power of the WP REST API. We will be using basic authentication throughout this series due to its ease of use, but it’s recommended that you use OAuth 2.0 authentication, as provided by the WordPress REST API Authentication plugin, for your production servers.
The WordPress REST API Authentication plugin enhances the security of the WordPress REST API by adding authentication mechanisms to control access to API endpoints. It comes with a few authentication methods:
- basic authentication
- API key authentication
- JWT authentication
- OAuth 2.0 authentication
Once the authentication is set up, you can define access control rules for different API endpoints. It allows you to configure which users or roles have permission to access specific endpoints. It also provides options to restrict access based on user roles, capabilities, or specific user IDs.
In the current part of the series, we will get our very first hands-on experience with the WP REST API. We will:
- analyze the structure of a
GET
request - check out how the
OPTIONS
request self-documents the API - send requests to the server for data retrieval
- analyze the server response that includes properties, schema, and links
So let’s begin by analyzing the structure of a simple GET
request.
Anatomy of a GET
Request
Before we delve into the details of retrieving any data with the WP REST API, we need to familiarize ourselves with the syntax of a request that is sent to the server. This will lay a solid foundation for our future interactions with the WP REST API.
Consider the following request sent to the server:
1 |
$GET https://localserver/wp-json/wp/v2/posts
|
The type of request we are sending is GET
—one of the six HTTP verbs we looked at in the initial part of this series. A GET
request is used to retrieve data from the server. Hence, when executed at the server, the above request retrieves a collection of all post objects in the form of JSON data.
Considering the request URI, we can break it into the following parts:
-
https://localserver/
: The URL of my local development server. It could be any URL depending on where your WordPress installation is located. -
/wp-json
: It is the endpoint prefix of the WP REST API. -
/wp
: The namespace of the WP REST API. -
/v2
: It is the version of the WP REST API. -
/posts
: It is the resource which we want to retrieve from the server.
The namespace prevents the overriding that might occur when running multiple plugins with each providing its own abstraction layer for the RESTful API. Hence, each abstraction works in its own boundary, without affecting methods and properties that belong to some other abstraction.
In addition to retrieving a collection of resources (posts) using the above URI, we can also retrieve a specific resource by mentioning its ID:
The above request will return a post object as it looks down for a post resource which has an ID of 100.
More often than not, we also need to search for posts that meet some specific criteria. For example, you can get the posts filtered by category, as shown in the following snippet.
1 |
$ GET /wp/v2/posts?categories=20,30 |
By sending the above request, we can retrieve all the posts belonging to a category of ID 20 and 30. As you can see, you can pass one or more category IDs in the categories
argument, and it should return posts with specific terms assigned in the categories taxonomy.
The above syntax is equivalent to the following WP_Query()
call:
1 |
<?php
|
2 |
$query = new WP_Query( array( |
3 |
'tax_query' => array( |
4 |
array( |
5 |
'taxonomy' => 'category', |
6 |
'field' => 'term_id', |
7 |
'terms' => array( 20, 30 ), |
8 |
),
|
9 |
),
|
10 |
) ); |
Hence, the above GET
request will retrieve a list of posts that belong to both categories having an ID of 20 and 30. The same syntax can also be used for array arguments having more than two elements.
Now that we have learned about formatting a GET
request and providing its parameters, it’s time to take a look at the OPTIONS
request. An OPTIONS
request makes it easy to navigate through the API and actually serves as a self-documenting way to make the API more accessible by documenting all the available HTTP methods on an endpoint and, in turn, the arguments they support.
Navigating Through the API Using the OPTIONS
Request
As mentioned before, the OPTIONS
request can be extremely helpful in exploring the API. It mentions all the endpoints that belong to a certain route and provides a list of parameters these endpoints support for CRUD operations.
Let’s send an OPTIONS
request to the /wp/v2/posts
route to check which endpoints it supports and which parameters we can pass along the GET
request to query data:
1 |
$curl -X OPTIONS /wp/v2/posts |
I’ve used curl to send the above request, but you can use any tool of your choice, including Postman. Be sure to include the full path to the above route, including the path of your server.
1 |
{
|
2 |
"namespace": "wp/v2", |
3 |
"methods": [...], |
4 |
"endpoints": [...], |
5 |
"schema": {...}, |
6 |
"_links": {...} |
7 |
}
|
The above OPTIONS
request to the /wp/v2/posts
route returns data in the JSON format, which contains five properties:
namespace
methods
endpoints
schema
_links
1 |
{
|
2 |
"namespace": "wp/v2", |
3 |
....
|
4 |
}
|
The namespace
property identifies the namespace of the current plugin. In our case it’s wp/v2
, signifying version 2 of the WP REST API. We have already looked at the namespace and the purpose it serves in the previous section.
1 |
{
|
2 |
...
|
3 |
"methods": [ |
4 |
"GET", |
5 |
"POST" |
6 |
],
|
7 |
...
|
8 |
}
|
The methods
property contains an array of all the methods supported by the current route. By looking at the response the above request returned, it’s clear that the /wp/v2/posts
route supports two methods, namely GET
and POST
. It means that we can use the /wp/v2/posts
route to retrieve posts, as well as creating a new post. We will deal with the POST
method in the next part of this series, so let’s just focus on the GET
method for the time being.
The next property—endpoints
—contains an array of the supported endpoints for the current route. This property is directly linked to the previously mentioned methods
property as it lists endpoints for the supported methods.
1 |
{
|
2 |
...
|
3 |
"endpoints": [ |
4 |
{
|
5 |
"methods": [ |
6 |
"GET" |
7 |
],
|
8 |
"args": {...}, |
9 |
"allow_batch": {"v1":true} |
10 |
},
|
11 |
{
|
12 |
"methods": [ |
13 |
"POST" |
14 |
],
|
15 |
"args": {...}, |
16 |
"allow_batch": {"v1":true} |
17 |
}
|
18 |
],
|
19 |
...
|
20 |
}
|
The endpoints
property contains object values that in turn contain three properties, namely methods
, args
, and allow_batch
. The methods
property contains an array of HTTP methods, and the next args
property contains all the supported arguments for these methods. Finally, the allow_batch
property is used to know if the endpoint supports the batch request functionality. These are the arguments that we send along the request in the form of URI parameters.
Looking at the arguments supported by the GET
method, we come across more than 20 arguments, including context
, page
, per_page
, etc. These argument objects mainly contain three properties: required
, type
, and default
. The required
property indicates whether the argument is required, and the default
property represents the default value of the argument. On the other hand, the type
property indicates the type of value one should pass. Apart from that, it may also contain other argument-specific properties.
1 |
"methods": [ |
2 |
"GET" |
3 |
],
|
4 |
"args": { |
5 |
"context": { |
6 |
"required": false, |
7 |
"default": "view", |
8 |
"type": "string", |
9 |
"description": "Scope under which the request is made; determines fields present in response." |
10 |
},
|
11 |
"page": { |
12 |
"required": false, |
13 |
"default": 1, |
14 |
"type": "integer", |
15 |
"description": "Current page of the collection.", |
16 |
"minimum": "1" |
17 |
},
|
18 |
"per_page": { |
19 |
"required": false, |
20 |
"default": 1, |
21 |
"type": "integer", |
22 |
"description": "Maximum number of items to be returned in result set.", |
23 |
"minimum": "1", |
24 |
"maximum": "100" |
25 |
},
|
26 |
}
|
The schema
property in the returned response documents all the properties for the current resource. The schema defines a structure for data in the JSON format. The schema format used in the WP REST API is based on draft 4 of the JSON schema specifications.
The last _links
property holds an array of objects containing the links of associated resources. The key in the object specifies the relationship type (e.g. author
, collection
, self
, comments
, etc.), with its value being the link to that associated resource. This linking standard is based on HAL (Hypertext Application Language). You can find out more about HAL by reading the specifications authored by Mike Kelley.
In a similar manner, we can send an OPTIONS
request to other routes as well, including those of users, comments, media, pages, etc., to check their supported methods and arguments. OPTIONS
requests are your best friend when working with the WP REST API.
The WP REST API provides yet another way to assess the API availability by sending a GET
request to the /wp-json
index route. This will list all the routes and their endpoints along with their supported methods and arguments.
1 |
$curl -X GET http://wordpress-server/wp-json |
The above request will return a response object containing a routes property as follows:
This feature is immensely powerful as it lists all the routes and their supported methods and arguments, thus eliminating the need for all these to be documented externally. We will be referring to this response object when performing CRUD operations on different resources.
Having looked at our options to explore the API, let’s now begin working with the WP REST API to retrieve data from the server.
Working With Posts
By now, we have familiarized ourselves with the OPTIONS
request, which is a self-documenting way to assess the API availability. We also looked at how it shows supported methods and arguments for a given route. Using this knowledge, we are now ready to retrieve different resources from the server using the WP REST API.
The resource we will begin with is the posts
resource, since it’s the main building block of WordPress. We will deal with retrieving posts using different criteria. By applying this knowledge, you will be able to query posts using the WP REST API just as you do with the WP_Query class.
Throughout this series, we have been working with the posts
resource to demonstrate example requests and their responses, and we already know how to retrieve a post collection and an individual post by its ID. So we won’t be covering that again. Instead, we will look at some more advanced ways to retrieve posts using the top-level parameters.
Working With Top-Level Parameters
The WP REST API exposes some of the most commonly used query variables for posts directly on the GET
endpoint. These parameters are:
Parameter | Meaning |
---|---|
context |
The scope of the request. Possible values could be view , embed , or edit . The default is view . |
page |
The current page of the post collection. It defaults to 1 . |
per_page |
Total number of posts per page. It defaults to 10 . |
search |
The search query. Limit results to the matching string. |
after |
Returns only those posts published after the date given in this parameter. |
modified_after |
Returns only those posts modified after the date given in this parameter. |
author |
The author ID. Used to limit results belonging to a specific author. |
author_exclude |
The result set excludes posts assigned to specific authors. |
before |
Returns only those posts published before the date given in this parameter. |
modified_before |
Returns only those posts modified before the date given in this parameter. |
exclude |
An array of post IDs to exclude from search results. |
include |
Limit the results to post IDs specified in this array. |
offset |
Offset the search results by the specified number. |
order |
The order of the collection. Can either be asc or desc . |
orderby |
Sorting attribute of the collection. Possible values can be author , date , id , include , modified , parent , relevance , slug , include_slugs , and title . |
search_columns |
You can specify the array of column names to be searched. |
slug |
Limit the results to a post having a specific slug. |
status |
Used to limit the collection of the posts having a particular status. |
tax_relation |
Used to limit the result set based on the relationship between multiple taxonomies. |
categories |
Filter the result set by the terms assigned in the categories taxonomy. |
categories_exclude |
Filter the result set to items except those with specific terms assigned in the categories taxonomy. |
tags |
Filter the result set by the terms assigned in the tags taxonomy. |
tags_exclude |
Filter the result set to items except those with specific terms assigned in the tags taxonomy. |
sticky |
Used to limit the result set to items that are sticky. |
The context
parameter is used to fetch posts depending on the scope we are working in. If we are just listing posts on an index page, then we are good to go with the view
context. But if we are retrieving posts in order to edit them, then we need to use the edit
context:
1 |
$GET /wp/v2/posts?context=edit |
The edit
context parameter introduces an additional raw
field in fields like title
, content
, and excerpt
. The value of this raw
field can be echoed out in the editor for editing the content.
Using the edit
context requires you to be authenticated as a user with edit_posts
privileges.
Using embed
as the value of the context
parameter fetches the collection of the posts with a minimal subset of their properties.
The other parameters mentioned above are pretty self-explanatory, and you can play around with them in your HTTP client.
These are the basic parameters that allow you to query posts based on certain criteria.
How to Use Other Criteria to Filter Records
In addition to retrieving a collection of posts using some basic top-level parameters, the WP REST API also allows you to filter records by various other criteria as well. By using this syntax, we can query posts the same way as we do when working with the WP_Query()
class.
Pagination parameters are the most important of all the filters, as they are used extensively on post listing pages. The pagination parameters allow us to show a specific number of posts per page and navigate to a specific number of pages containing posts.
By default, a GET
request retrieves a collection of ten posts per page. Let’s see how we can submit a GET
request to retrieve only five posts per page:
1 |
$GET /wp/v2/posts?per_page=5 |
The above request uses the per_page
variable that you might be familiar with if you have worked with WP_Query()
.
The page
parameter is used in conjunction with the per_page
parameter, and it’s used to navigate to a specific number of pages. After having retrieved five posts per page, we would make the following request to navigate to the second page:
1 |
$GET /wp/v2/posts?per_page=5&page=2 |
The per_page
and page
filters can be extremely handy when working to build pagination on listing pages using the WP REST API.
In addition to the collection of posts the above request returns, the server also returns a number of headers with a response that contains useful information, including the total number of posts and the number of pages. These values are contained in the X-WP-TotalPages
and X-WP-Total
response headers.
The X-WP-TotalPages
and X-WP-Total
response headers are extremely useful when creating pagination using the WP REST API as they list the total number of pages and the total number of posts respectively.
Apart from pagination filters, you can also filter posts by their dates.
So if we are looking for the posts published on the date 2015-10-15 (yyyy/mm/dd), this can be achieved by the following query:
1 |
$ GET /wp/v2/posts?modified_after=2015-10-14&modified_before=2015-10-16 |
We have already seen in the previous section of this tutorial how we could fetch posts belonging to a specific category or multiple categories using the categories
parameter. Let’s see how to show posts belonging to categories having an id of 5 and 6:
1 |
$ GET /wp/v2/posts?categories=5,6 |
The above request will retrieve a list of all the posts belonging to categories having an id of 5 and 6.
The opposite effect could be achieved by using the categories_exclude
parameter in the following manner:
1 |
$ GET /wp/v2/posts?categories_exclude=5,6 |
This will retrieve a list of posts, while excluding all those posts belonging to categories having an ID of either 5 or 6.
Now that we have looked at different options when querying posts with the help of the WP REST API, we are ready to further advance our journey and look at some other resources supported by the WP REST API.
Working With Post Revisions, Categories, and Tags
Post revisions provide a way to view and restore edits made to a post. The WP REST API provides a way to view all the revisions of a post by querying the /posts/<id>/revisions
endpoint. Hence, for a given post having an ID of 10, all the revisions can be retrieved by sending the following request:
1 |
$ GET /wp/v2/posts/10/revisions
|
The above request will return an array containing revision objects. The revisions object contains a subset of properties found in the post object. Below is an example revision object in Postman:
A specific revision can be retrieved given that we know its ID. So a revision with an ID of 2 on a post with an ID of 10 can be retrieved by the following object:
1 |
$ GET /wp/v2/posts/10/revisions/2
|
The above request will return a single revision object.
Other than post revisions, categories for a specific post can be retrieved by the following request:
1 |
$ GET /wp/v2/categories?post=<post_id> |
And for the tags, we use the following request, with <post_id>
being the ID of the post:
1 |
$ GET /wp/v2/tags?post=<post_id> |
If we need to retrieve post meta for a post with an ID of 10, we send the following request as an authenticated user:
1 |
$ GET /wp/v2/posts/10/meta
|
This will return an array of meta objects.
Please note that to work with post and page meta in WP REST API, you need to have the companion plugin installed, which is available on GitHub from the WP REST API team.
Working With Other Resources
By now, we have gained a pretty solid foundation for working with the WP REST API to retrieve data. We have already looked at the options request and how it helps us explore the API without the need for external documentation.
You can always send an OPTIONS
request to a particular resource and check what endpoints and parameters it supports. If you need to list all the routes that the WP REST API provides, you can send a GET
request to the index endpoint at /wp-json
as we learned to do at the beginning of this tutorial.
Considering this advantage of self-documentation, I don’t think that we further need to explore each individual resource in this tutorial, as you are now able to do that on your own.
What’s Up Next?
In this lengthy tutorial, we learned to explore the API using the OPTIONS request and retrieve data from the server using the WP REST API. We just looked at a handful of resources including posts, post revision, and post meta, as we couldn’t cover all the supported resources in just one tutorial. But you should now be able to explore the API on your own using the techniques we covered in this tutorial.
WordPress has an incredibly active economy. There are themes, plugins, libraries, and many other products that help you build out your site and project. The open-source nature of the platform also makes it a great option from which you can better your programming skills.
In the next installment of this series, we will learn to perform the other three operations of CRUD, i.e. create, update, and delete resources. So stay tuned.