WordPress REST API Tutorial – A Beginner’s Guide

Are you looking for a beginner-friendly WordPress REST API tutorial? Then you’ve come to the right place! In this article, we will introduce you to the WordPress REST API project, explain why it is such a big deal, and offer some insights on how to use it.

Introducing the WordPress REST API

REST (Representational State Transfer) API is a software architectural style that determines how web services communicate with each other through HyperText Transfer Protocol.

In June 2013, Ryan McCue and Rachel Baker from WordPress uploaded the REST API project to GitHub. After gaining a lot of public support and attracting nearly 100 contributors for future improvement, the project was added to the WordPress core in December 2015.

Now, almost every professional working with WordPress has heard of the REST API. However, since its core integration, only advanced developers have taken the time to learn how powerful this new feature can be. This is very unfortunate since this tool can open up endless possibilities to extend your WordPress website.

WordPress REST API aims to provide a built-in API that can be integrated with themes, mobile applications, and more. It lets WordPress to interact with any application, and developers can even use it to build their own APIs.

You can take advantage of it in your projects, too. For example, Event Espresso uses the WordPress REST API to provide access to their internal infrastructure, making it possible to develop apps based on their services.

How the WordPress REST API Works

There are many types of Application Programming Interfaces (API) right now, but REST stands out as a modern standard. It works by manipulating textual data from one place to another without direct access to a database or user interface.

REST API is delivered via HyperText Transfer Protocol (HTTP) endpoints, using JavaScript Object Notation (JSON) formatting. These endpoints represent the posts, pages, and other WordPress data types.

If you have never worked with JavaScript or its object notation before, we recommend learning about the basics of JSON first. It will help you better understand this WordPress REST API tutorial.

Why WordPress REST API Matters for Developers

Thanks to JSON formatting, WordPress REST API allows WordPress to exchange data with other websites and software written in any programming language. Hence, developers are not constrained to PHP anymore, and they can use WordPress to handle the data via REST API.

The increasing focus on the API also raises arguments about the most important programming language to learn. Since the REST API is based on JavaScript, you may soon find that server-side JavaScript can replace PHP altogether.

This notion is backed up by the fact that the new WordPress.com software, Calypso, runs entirely on JavaScript and REST API.

Additionally, by standardizing the way applications interact with WordPress data, WordPress development will become simpler and faster.

For that reason, our WordPress REST API tutorial is here to encourage you to pay more attention to this feature.

5 Steps for Getting Started With the WordPress Rest API

In this WordPress REST API tutorial, we will be using the command-line interface (CLI) to execute all of the requests. CLI enables you to easily interact with the REST API without having to write additional scripts to request and process the information.

The first thing you need to do is open a CLI program on your computer: Terminal for macOS and Linux, and PuTTY for Windows. After that, copy your shared or dedicated IP address and log in with your SSH credentials.

We also recommend using a demo site or local testing for this tutorial. Furthermore, make sure that it runs on WordPress version 4.4 or higher as well.

Step 1: Familiarize Yourself With the Key Concepts of REST API

We’ll begin our WordPress REST API tutorial by explaining the key concepts and terms:

• Routes & endpoints — a route is a URL that you can map to different HTTP methods, while an endpoint is a connection between an individual HTTP method and a route. /wp-json/ is an example of a route, and it contains all corresponding endpoints.
• Requests — an instance of WP_REST_Request. It is used to store and retrieve information for the current request.
• Responses — provides the data you requested or returns an error to let you know what went wrong.
• Schema — shows you a list of all properties and input parameters that REST API can accept and return.
• Controller classes — the place where you manage REST API moving parts.

Step 2: Get To Know the Most Useful REST API Endpoints

In this part of the REST API tutorial, we’ll show you several handy REST API endpoints that you can test with your site:

1. First of all, you’ll want to know how to construct an HTTP call to the REST API. The base of every WordPress REST API call is as follows:

   http://yourdomain.com/wp-json/

2. Then, you can test the connection by executing the curl command in your CLI:

   curl -X OPTIONS -i http://yourdomain.com/wp-json/

   You should be prompted with a successful HTTP message:

   HTTP/1.1 200 OK
   Date: Wed, 23 Oct 2019 19:51:41 GMT
   Server: Apache/2.4.29
   X-Robots-Tag: noindex
   Link: <http://yourdomain.com/wp-json/>; rel="https://api.w.org/"
   X-Content-Type-Options: nosniff
   Access-Control-Expose-Headers: X-WP-Total, X-WP-TotalPages
   Access-Control-Allow-Headers: Authorization, Content-Type
   Allow: GET
   Transfer-Encoding: chunked
   Content-Type: application/json; charset=UTF-8

3. Next, you can rinse and repeat this command using several endpoints. This time, we’ll simply use the GET version of curl to grab a JSON list of your WordPress posts. To do that, you can use the following command:

   curl -X GET -i http://yourdomain.com/wp-json/wp/v2/posts

   Alternatively, you might want to try this command to check out all of your existing WordPress pages:

   curl -X GET -i http://yourdomain.com/wp-json/wp/v2/pages

If you want to see more examples, WordPress REST API offers a reference handbook that contains a lot of useful endpoints.

Step 3: Learn the Basics of REST API Authentication

Some actions and data within the REST API are public, while others require you to log in as an administrator. However, since it’s REST API,  there is nowhere to log in.

To get around this issue, you can authenticate yourself when making any call that requires administrative access, such as viewing unpublished content or updating a post.

For this tutorial, we’ll be using the WordPress REST API Basic Auth plugin. It is a simple developer-only plugin to help you learn the REST API, but it is not intended for live sites. Here’s how to install the plugin:

1. Download the WordPress REST API Basic Auth plugin.
2. Log in to your WordPress Dashboard and go to Plugins -> Add New. Click on the Upload Plugin button and select the plugin’s zip file.
3. Go to the Installed Plugins menu and activate the plugin from there.
4. Once Basic Auth is installed, open CLI and authenticate an API request by utilizing the user flag. Here is an example of how to apply the user authentication method, using curl to view unpublished posts:

   curl -X GET --user username:password -i http://yourdomain.com/wp-json/wp/v2/posts?status=draft

Now that you get the hang of basic authentication, you can explore other recommended methods in the REST API documentation.

Step 4: Select Your First WordPress Post With the REST API

Once you understand how to make basic calls to the REST API using the curl command, you can proceed with selecting a specific post:

1. First, list out all your posts as we did previously:

   curl -X GET -i http://yourdomain.com/wp-json/wp/v2/posts

2. Find the ID of a post you’d like to update. You’ll need to add an ID to the end of your query in order to select an individual post:

   curl -X GET -i http://yourdomain.com/wp-json/wp/v2/posts/<ID>

You can use this command to pick a given ID for any REST API endpoint, whether it’s a post, page, or taxonomy.

Step 5: Update Your First WordPress Post With the REST API

Finally, let’s try sending an update to your selected post. For this REST API tutorial, we’ll try to rename our post’s title by using the POST command. Don’t forget to include the authentication credentials.

New changes will be shared using the d flag at the end of our command.

1. In this example, you’ll pass a custom JavaScript object variable (title) to a custom value (My New Title):

   curl -X POST --user username:password http://yourdomain.com/wp-json/wp/v2/posts/PostID -d '{"title":"My New Title"}'

curl -X GET -i http://yourdomain.com/wp-json/wp/v2/posts/PostID

Congratulations! You have just made your first administrative edits using the WordPress REST API.

Conclusion

REST API is a powerful addition to WordPress’ core and developers have begun to uncover its capabilities, such as creating a headless WordPress site. Therefore, learning to work with it can improve your skills and enable you to create apps that use WordPress’ services.

In this WordPress REST API tutorial, you have learned the five important steps to master this feature:

1. Familiarize yourself with the key concepts of the REST API.
2. Get to know the most useful REST API endpoints.
3. Learn the basics of REST API authentication.
4. Select your first WordPress post with the REST API.
5. Update a WordPress post with the REST API.

While this WordPress REST API tutorial only scratches the surface of its capabilities, we think it’s still a good starting point before you get deeper into it.

Do you have any questions? Let us know in the comment section below!

The author

Will M.

Will Morris is a staff writer at WordCandy. When he's not writing about WordPress, he likes to gig his stand-up comedy routine on the local circuit.

More from Will M.