WordPress Tutorial

A Beginners’s Guide to the WordPress REST API

A Beginners’s Guide to the WordPress REST API

Nearly every professional working with WordPress has heard of the REST API by now, thanks to its core addition in late 2015. However, for the most part, only advanced developers have taken the time to learn how powerful this new feature can be.

The WordPress REST API packs a wallop in every up-to-date installation, by providing a built-in API that can be integrated into themes, mobile applications, and more. In other words, it enables developers to separate the front end interface from data management, letting any application interact with WordPress. Learning how to work with this tool can open the doors to nearly endless possibilities for extending your WordPress website.

In this article, we will introduce you to the WordPress REST API project, explain why it is such a big deal, then offer some insight on how to use it. There’s no time to waste, so let’s get started!

Introducing the WordPress REST API

WP REST API project homepage

The WordPress Representational State Transfer (REST) API project claims that WordPress is making moves towards becoming a fully fledged application framework. Its very existence supports this claim, as it adds an industry standard REST API to the WordPress core.

The project was first uploaded to GitHub for development in June 2013 by Ryan McCue and Rachel Baker. The independent REST API plugin was integrated into WordPress core in December 2015, after gaining a lot of public support and attracting nearly 100 contributors to work on refining its abilities.

Since its debut to the WordPress core, the REST API has proven to have many uses. Here are just a few ways you can take advantage of it in your projects, as inspired by real world examples:

  1. Event Espresso uses the REST API to provide developer access to their internal infrastructure, making it possible to develop apps based on their services.
  2. Simmer enables developers to access the API in order to extend their recipe functionality into fully fledged mobile applications or customized themes.
  3. JoinIn powers their own ’embeddable’ widget using the REST API, populating it with appropriate data wherever it’s displayed.

This is just the tip of the iceberg when it comes to innovative uses for the REST API. However, let’s now discuss how the REST API works.

How the WordPress REST API Works

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

REST APIs are delivered via Hyper Text Transfer Protocol (HTTP) endpoints, using JavaScript Object Notation (JSON) formatting. In simpler terms, these technologies provide access to the API using unique web addresses to deliver data that behaves like JavaScript objects.

If you have never worked with JavaScript or its object notation before, it might be a smart idea to start out by learning the basics of JSON. Once you’re more comfortable with the concept of a REST API, let’s talk about the major impact it will have on all WordPress developers.

Why the WordPress REST API Matters for Developers

WordPress REST API Handbook

The WordPress REST API is a universal connector from any WordPress installation to any given application on a web server or user operating system. Ultimately, this means the only limit to what can be built using WordPress now is our own imaginations. You can build any application, code with any platform or language, and use WordPress to handle the data via the REST API. The implications of this are enormous, thanks to WordPress’ open and friendly community.

Additionally, since the REST API is based on JavaScript, this increasing focus on the API marks a shift in which programming languages are most important to learn. You may soon find that server-side JavaScript is the new PHP. This can already be seen in the new WordPress.com software, Calypso, which runs completely on JavaScript and the REST API.

By standardizing the way applications (including WordPress’ core) interact with WordPress data, WordPress development will become simpler and more intuitive. What’s more, it will become easier to integrate with third-party platforms.

However, the transition period may be a bit rough, which is why it’s important to start learning how to use this technology now. It’s time to take the first steps towards using the REST API in your own work!

5 Steps For Getting Started with the WordPress REST API

As we covered earlier, the REST API can be used with any application or programming language that can call an HTTP endpoint (which is most of them). Therefore, we’ll focus on using the command line to execute REST API requests, because it is the simplest method and has the fewest opportunities for programmatic bugs to interrupt your learning.

To do this, you’ll want to open up the Command Line Interface (CLI) program on your computer – Terminal on macOS and Linux, and Command Prompt in Windows. The CLI enables you to directly interact with the REST API, without needing to write additional scripts to request and process the information. Any request you make in the CLI can be scripted into PHP, JavaScript, and other languages, but the method will vary for each. Giving commands in the CLI is straightforward. Simply type in the desired command and press ENTER on your keyboard.

We also recommend setting up a demo site or testing locally, rather than completing this tutorial on a live site. Finally, the only other requirement is that your WordPress site is running on version 4.4 or higher. When you’re ready, let’s get started!

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

Before you begin, it’s a smart idea to familiarize yourself with all of the REST APIs moving parts. There are five key concepts and terms you should be familiar with. Let’s go over them now:

  1. ‘Routes’ and ‘Endpoints’. This is the most important aspect of the REST API to understand. Routs help you navigate your way through endpoints, which are when a specific HTTP method (e.g. a static dataset or an action) is connected to a specific route. For example, /wp-json/ is a route configured as an endpoint, designed to show us available routes.
  2. Requests. These are made by triggering the correct endpoints and passing along data.
  3. Responses. In short, this provides the data you requested or returns an error to let you know what went wrong.
  4. Schemas. These are the templates responses follow, so you always know exactly where to look for the right data.
  5. Controller classes. In layman’s terms, they enable you to build your own routes and endpoints. For now, you don’t need to worry about these, although they’ll become more useful further along.

Once you understand these five concepts, you can begin to delve deeper into the REST API itself, starting with its endpoints.

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

The WordPress REST API offers a reference handbook loaded with all of the endpoints you’ll find most useful. First, 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, replacing the yourdomain.com placeholder with your own:


You can test the connection by executing the curl command in your CLI using your own URL:

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

You should be greeted with a successful HTTP message. You can then rinse and repeat this command using several of the main endpoints. This time, we’ll simply use the GET version of curl.

To grab a JSON list of your WordPress posts, you can use the following:

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

Alternately, try this to check out all of your existing WordPress pages:

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

You can experiment with each of these endpoints (and more!) in the CLI to review what sort of response is returned for each.

Step 3: Learn the Basics of REST API Authentication

Now it’s time to learn about authentication. Some actions and data within the REST API are public, while others require you to be logged in as an administrator. However, this is a REST API, so there is nowhere to log in. Instead, you can authenticate yourself when making any call that requires administrative access, such as viewing unpublished content or updating a post.

Start by installing the WordPress REST API Basic Auth plugin. This is a simple developer-only plugin to help you learn the REST API quickly, and is not intended for live sites. However, the installation process is as any other plugin.

Once Basic Auth is installed, you’ll be able to authenticate over the CLI with 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

Authentication will be required for anything other than viewing public information. Once you get the hang of basic authentication, you can explore the other options recommended by the REST API documentation for your production code.

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

Once you understand how to make basic calls to the REST API using curl, try to select a specific post. First, list out all your posts as we did previously:

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

Next, find the ID of a post you’d like to update. You’ll add this ID to the end of your query in order to select only that individual post:

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

You can use this to select a given ID for any REST API endpoint, whether you want to view 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. Instead of using the OPTION or GET commands, this time we want to POST a change. GET is used to read data, while POST is used to send it.

Let’s rename your post’s title to something else, by sending a POST request along with your authentication credentials. New changes will be shared using the d flag at the end of your command. You’ll pass a custom JavaScript object setting the title variable to a custom value, such as My New Title, as seen in the example code below:

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

Be sure to replace the username, password, post ID, and title name with your own information. You can reselect the individual post to verify the new changes:

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

Congratulations! You just made your first administrative edits using the WordPress REST API. Of course, this basic tutorial barely scratches the surface of what the REST API can do, but at this point the sky’s the limit!


The WordPress REST API is a powerful new addition to WordPress’ core, and few developers have even begun to scratch the surface of its capabilities. As a consequence, getting onboard now and learning to work with it can make you more valuable as a developer, and enable you to create apps using WordPress as a framework.

To review, here are our five steps to learning how to interact with the WordPress REST API:

  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.

What questions do you have about the WordPress REST API? Let us know in the comments section below!

About the author

Will Morris

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.


Click here to post a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Get Exclusive Content

Join thousands of webmasters who get our free newsletter with tips on how to drive more traffic and revenue to their websites!

Please wait...

Thank you for sign up!

More in WordPress Tutorial
Best WordPress Plugins
14 of the Very Best WordPress Plugins in 2019