If you’ve been around the WordPress space for awhile, you’ve probably heard of the WordPress REST API. If you’ve done any research, you may have been really intimidated by what you found — namely, a LOT of technical jargon and seemingly no clear path on how to actually use it.
Today I’m going to show you (the absolute beginner) how to use the WordPress REST API. First, I’ll show you how to get some data from another WordPress site. Then, I’ll introduce a few key terms once you see how it works.
Before we begin, open up Chrome and install the JSON Viewer extension. When you try the examples below, the output will be presented in a much more readable format.
Using the WordPress REST API
To use the WordPress REST API, simply add
/wp-json/wp/v2/posts to the end of your WordPress site URL. This will give you a list of posts (in JSON format). The default number of posts returned is 10, but you can choose to show more or less with the
per_page argument — we’ll talk about that below.
For example, visit https://renemorozowich.com/wp-json/wp/v2/posts. You did it! You just used the WordPress REST API to view my 10 post recent posts. Easy, right?
Arguments to Return Specific Posts
There are also several arguments you can append to get specific posts.
per_page will let you specify how many results you want to return. Here I’m searching for the two most recent blog posts: https://renemorozowich.com/wp-json/wp/v2/posts?per_page=2
order will let you specify how to return the results, in order descending (default) or ascending. Here I’m searching for my blog posts in ascending order: https://renemorozowich.com/wp-json/wp/v2/posts?order=asc
categories will show you posts from a specific category. (You have to know the ID, which you can find if you add
/wp-json/wp/v2/categories to the end of your main URL.) Here I’m searching for posts in the Technical category (ID 45): https://renemorozowich.com/wp-json/wp/v2/posts?categories=45
search will show posts that include a specific search phrase. Here I’m searching all of my posts for the word plugin: https://renemorozowich.com/wp-json/wp/v2/posts?=search[plugin]
An Example Using the REST API
I wrote a little plugin to get the two post recent posts from Sumy Designs, a web design company in Indiana. The post name, date and permalink are returned.
Here is the output:
If you visit this page again in a few days, you’ll see that the posts will have changed. The REST API is getting the two most recent posts, which will change each time they publish a new post.
And here is the code:
To implement, save the code and upload it to your plugins folder. Then add the shortcode [sc_get_posts_via_rest] to your post or page.
Some Key Terms
I’d be remiss if I didn’t mention a few key terms.
Application Programming Interface — the rules that specify the way for two separate systems to talk to each other. Check out What is an API and Why Should I Use One?.
Representational State Transfer — a specific type of API used on the web. What is REST? gets sightly technical, but it’s easier to understand than most.
In all of the examples above, we’re using the HTTP GET method to get posts. We make a request in the browser (Hey WordPress site, gives me the two most recent posts) and the server sends back a response (Here are the two most recent posts).
You can also POST, PUT or DELETE (to name a few) which will actually make changes to the data by adding, changing or removing it. In these cases, you need to authenticate to be able to modify the data. Read about 7 HTTP methods here.
Routes and Endpoints
An endpoint is a function available through the API. Each endpoint performs a specific task; for example — getting a post, updating the author or deleting a comment.
A route is the name you use to access the endpoint. The route to this post is
wp-json is the base path for the API itself). Within this route, there are various endpoints.
Ready for More?
If you want to learn more about the REST API, check out the handbook.
Lynda.com has a great learning path — Become a RESTful API Developer. (Check with your local library to see if they offer free lynda.com subscriptions with your membership.)
Lastly, here are some other great articles on the REST API:
- A Quick Start Guide To The WordPress REST API
- WordPress REST API: What It Is and How to Get Started Using It