Join Morten Rand-Hendriksen for an in-depth discussion in this video Check the API index for available routes, endpoints, and arguments, part of WordPress: REST API.
- [Instructor] Postman is technically a Chrome extension. Even so, it acts like a standalone application on your computer. So, if you're on a Windows computer or on a Mac, you can boot up Postman independently and have it live side-by-side with your browser. To boot it up on Windows, hit the Windows key, or on Mac, hit Command + Space and type in Postman, and the application starts up. Postman works pretty much exactly the same way as a web browser, in that you can request any content that's available through the web protocol on your computer.
That means you can access any WordPress site live on the web, and you can also access any WordPress site live on your computer in your development environment. On my computer, I have a WordPress site running under Wamp server. It has the virtual URL, and from Postman, I can access that exact same site, restful.dev/wp-json/wp/v2/posts, and in return, I get the 10 most recent posts in JSON format. Moving forward in the course, I'll be using this site restful.dev as my example so I can experiment with it and I am not relying on a site that lives live on the web, and you should do the same with your own site.
Now that you know how to interact with a WordPress rest API using Postman, I'm pretty sure the first question you have is, how do I know which roots I can use and what endpoints are available? After all, you don't want to get just the index. You want to get specific posts and specific pieces of content and display them in your app or on your front end application. The cool thing is, the WordPress rest API provides you with an index of all available roots and their endpoints. To get to that index, all you have to do is type in the URL to your site, followed by wp-json/wp/v2.
This is the root-level route and all other routes start with this and then continue onward. When you run this root-level route, you get the index of the API in the return, and that's what you see down here. This index gives you every single route and every single endpoint within that route, and then any arguments attached to those endpoints. In effect, it tells you exactly what you can access, what you can do with those pieces of information, and how can augment the request that's being sent to the server.
I'll scroll past this first endpoint here, which is the one we're currently at, the index, and find the one you'll be using the most, which is this one, wp/v2/posts. Out of the box, this route gives you the 10 most recent posts from your post index. So basically, what you see on the front end of any WordPress site. The posts route has two methods or endpoints. They are get, which gets data from the database, and pulls, which pulls data back to the database. In this course, we'll only be looking at the get method or endpoint.
Scrolling down to the endpoint, you'll see the first method. Get has a series of arguments. The first argument is context. This is set to default view, and this is what tells us how we want to get our content and what we want to do with it the rest API. We'll leave that one alone. The next argument is page. This tells the API what page in the index we want. So, as an example, by default, it's set to one. That means we get the first page of the index, the 10 most recent posts. If we set it to two, we get posts 11 to 20.
If we set it to three, we get posts 21 to 30 and so on, and so on. The per page argument tells the API how many posts we want per index page. The default is 10, and we can set this anywhere from one to 100. Just to answer the question you have right off the bat, there is no way of requesting every single post in a WordPress site using API. If you want to do that, you have to create a loop. The max number of posts you can get returned is always 100. Scrolling further down, you'll see the arguments we have available here pretty much match the arguments available to you using wp_query.
We can send a search, we can request posts that were posted after a certain date, or before a certain date, posts by a specific author, or posts except a specific author. We can exclude specific posts from a request, or include specific posts in our request. We can offset the page count. We can change the order of posts as they are displayed. We can order it by a bunch of different factors. We can request posts based on the slug, or the status, or what categories are in play, or exclude categories and tags in the same, and finally, we can limit results to only posts that are sticky.
So, how do you use all this information? Well, let me give you an example. I'll scroll up a bit here, and we'll find these two arguments here. Page and per page. So, first, I'll copy the URL and create a new tab here and paste it in. Then, I'll say posts, and this will return the 10 most recent posts in reverse chronological order, just like any blog index would do. To check that it's actually 10, we can collapse each of the post objects here, one, two, three, four, five, six, seven, eight, nine, 10.
10 posts objects, each of them containing one entire post. Now, I can augment this request using one of these arguments. So, let's use the page argument first. It's defaulting to one, meaning I get the first 10 posts. If I make the request again, you'll see the first post here is restful.dev/the-four-hours. If I go at the top here and say ?/page=2 and run the request again, you'll see the first page available is this one. WordPress, the Unknown User, the Need for Research.
If I go to the live site, which also displays 10 posts and go to page number two, you'll see the first post on page number two is WordPress, the Unknown User, and the Need for Research. So, this is how I create pagination using the API and traverse through all the available posts on the site. Now, the cool thing is, I can pass multiple different arguments to the same request. You saw directly under page, we had another argument called per page. That indicates how many posts are displayed in a single page.
I can append that as well. I'll just add an ampersand after page equals two, and then say per underscore page equals, and lets just, for the fun of it, say two. When I send this request, I now only get two posts in each index page. So, here we have number one and number two. If I change the page value to one, we then get two first posts The Four Hours and Semaphore. We can see that on the site. The Four Hours and Semaphore, and then if I change that number to two, the next that should appear is SVG at #WPYVR.
So, I'll go and change page to two. First post is SVG at #WPYVR. So, here's what I want you to take away from all this. Any time you're looking for a specific type of content or you want a specific type of return from the API. The first place you look is the root route, wp-json/wp/v2. This index will give you every single route, every single method or endpoint within that route, and every single argument you can pass to that method.
Combined, this gives you all the information you need to get the information you want from the WordPress database.
- Using a REST client to communicate with a REST API
- Reviewing available routes, endpoints, and arguments
- Adding custom post types and taxonomies
- Altering the API response
- Using PHP for resiliency
- Passing info using wp_localize_script()
- Setting up a REST API request through AJAX
- Outputting selected post data to the front end
- Formatting post data to match a theme
- Triggering AJAX for an infinite scroll effect
- Using AJAX to load subsequent responses