WP REST API: Retrieving Data

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:

1

$GET /wp/v2/posts/100

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:

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.