REST API

WordPress REST API

WordPress is the most popular CMS used on the internet and has been for some time. Because of popularity and being open source software there are 100s/1000s of people looking to improve the functionality of WordPress. One of the most exciting new features of WordPress is the HTTP REST API development.

WordPress Calypso

WordPress have started a project using the REST API which is great way to make sure all the endpoints that are needed by a normal website are there. Automattic have created a new project called Calypso, this is the new front-end to WordPress.com, it works as a desktop application and is built with JavaScript.

WordPress Calypso

Calypso can be used on all of your WordPress.com websites or any websites using the Jetpack plugin. It can be used to replace the admin area of your site and communicate with WordPress directly from this desktop application.

The main benefit to using JavaScript as the admin area via Calypso is speed, the pages will load almost instantly with data being imported via JavaScript AJAX requests.

Another benefit is that everything can be changed in real-time, so if you have a multi-author blog you can see the changes from the other authors in real-time.

The main frameworks that calypso takes advantage of is node.js and React.js libraries and a number of custom built functionality on to.

To see this in action, view the following video.

WordPress REST API

This is the sign of the web moving to the development process of API first, where your application will access data by going through an API rather than contacting a database directly and displaying the data on the page. This sort of development process has accelerated the use of JavaScript used in all website development. A while ago I noticed this trend in development practises and have decided to learn more about the JavaScript development process, you can read more about this change here Moving To Javascript Development.

The functionality for the REST API is intended to be merged into the WordPress core code but for the time-being it's development is happen has a feature plugin you can install on any WordPress website.

WordPress REST API

When this is installed on your site you'll be able to to get all the posts in your site by using the URL /wp-json/wp/v2/posts or if you want to search for posts with a certain keyword then you can make a GET request to /wp-json/wp/v2/posts?search=search+term.

Authentication

The way your RESP API will be able to be accessed by external websites is by authenticating the HTTP request by using either cookie authentication or OAuth authentication.

The REST API recommends that authentication should come down to the type of request you're making.

  • Are you a plugin/theme running on the site? Use cookie authentication
  • Are you a desktop/web/mobile client accessing the site externally? Use OAuth authentication, application passwords, or basic authentication.

Cookie authentication is already built into WordPress it's used when you log into your WordPress dashboard it will store a cookie on your machine to authenticate your requests, the REST API does this by WordPress Nonces.

OAuth Authentication is the main method when working with external websites. This process gives clients access to the API via tokens. Tokens can have an expiry to even turned off to stop clients accessing the API anymore. To use OAuth with the WordPress REST API you will also need to install the plugin OAuth.

WP API OAuth

When this is installed you'll need to create a new client which can be created from the admin area. The client will need be assigned a token allowing it access to the REST API by sending the authentication in the HTTP headers of the request.

What Data Can We Access?

As you need a plugin to access the REST API in WordPress one of the main worries is how much coverage do you get to the data in your WordPress CMS. Let's have a look at what data you can access from the REST API.

To see the data you can access you can view the API document using the link below:

WordPress REST API Reference

Posts

Using the API you can access all the posts stored in your WordPress CMS.

Get List Posts

To get a list of posts where you will commonly see on the homepage of a WordPress theme, where it displays the latest 10 posts of your blog you can use the following GET request.

GET /wp/v2/posts

The following arguments can be passed to the GET with through querystring to change the criteria of the posts returned.

An example of using these arguments for say getting all posts by a certain author can be done by using the author argument with the ID of the author.

GET /wp/v2/posts?author=1

If you want to create a search query then you can use the search passing in the search term that you want to use.

GET /wp/v2/posts?search=search+term

Get A Single Post

You're able to get a single post by the post ID by querying the API by using the following GET request.

GET /wp/v2/posts/:id

This will return the post information for this post ID. But in most websites you'll want to use a nicer looking permalink with the post slug, then you'll be able to get the full post information by using the GET request.

GET /wp/v2/posts?slug=post-url-slug

Create A Post

POST /wp/v2/posts

Update A Post

POST /wp/v2/posts/:id

Delete A Post

DELETE /wp/v2/posts/

Post API Reference

Post Revisions

When a post is being edited WordPress admin area will auto-save so the post, this adds a revision record into the database, the same happens when you update a post. This revision record can be used to display the history of the content. The following endpoints can be used to interact with the post revision records.

List Of Revisions For A Post

GET /wp/v2/posts/:parent_id/revisions

Retrieve a Post Revision

GET /wp/v2/posts/:parent_id/revisions/:id

Delete a Post Revision

DELETE /wp/v2/posts/:parent_id/revisions/:id

Post Revision API Reference

Pages

Pages is just another post type in the cMS, the endpoints therefore will be similar to the posts endpoints but change the posts with pages.

List All Pages

GET /wp/v2/pages

Retrieve a Page

GET /wp/v2/pages/:id

Create a Page

POST /wp/v2/pages

Update a Page

POST /wp/v2/pages/:id

Pages API Reference

Media

The media endpoints are used to handle the request for any sort of media files attached to a post such as featured images. A media endpoint can be used to customise the data attached to a certain image, such as the stored title, alt tag etc.

List Medias

GET /wp/v2/media

Retrieve a Media

GET /wp/v2/media/:id

Create a Media

POST /wp/v2/media

Update a Media

POST /wp/v2/media/:id

Delete a Media

DELETE /wp/v2/media/:id

Media API Reference

Post Types

If you have multiple post types in your application then you can use the following endpoints to interact with post type data.

List Types

GET /wp/v2/types

Retrieve a Type

GET /wp/v2/types/:type

Post Types API Reference

Post Statuses

Post statuses are used in the author workflow to show what stage the post is in, you can use these endpoints to get the registered post statuses in your applications.

List Statuss

GET /wp/v2/statuses

Retrieve a Status

GET /wp/v2/statuses/:status

Post Statuses API Reference

Comments

Using the following end points you can interact with comments published on the blog. This allows you to get all comments for a certain post and even create comments on your theme.

List Comments

GET /wp/v2/comments

Retrieve a Comment

GET /wp/v2/comments/:id

Create a Comment

POST /wp/v2/comments

Update a Comment

POST /wp/v2/comments/:id

Delete a Comment

DELETE /wp/v2/comments/:id

Comments API Reference

Taxonomies

Most websites will use taxonomies to organise the content structure of the site, using the following endpoints allow you to get a list of the taxonomies used on your website.

List Taxonomies

GET /wp/v2/taxonomies

Retrieve a Taxonomy

GET /wp/v2/taxonomies/:taxonomyId

Taxonomies API Reference

Categories

Use the following endpoints to interact with the category taxonomy on your WordPress website.

List Categories

GET /wp/v2/categories

Retrieve a Category

GET /wp/v2/categories/:id

Create a Category

POST /wp/v2/categories

Update a Category

POST /wp/v2/categories/:id

Delete a Category

DELETE /wp/v2/categories/:id

Categories API Reference

Tags

Use the following endpoints to interact with the tags taxonomy on your WordPress website.

List Tags

GET /wp/v2/tags

Retrieve a Tag

GET /wp/v2/tags/:id

Create a Tag

POST /wp/v2/tags

Update a Tag

POST /wp/v2/tags/:id

Delete a Tag

DELETE /wp/v2/tags/:id

Tags API Reference

Users

If you need to interact with Users on your WordPress website then there are the following endpoints to get users or create new users.

List Users

GET /wp/v2/users

Retrieve a User

GET /wp/v2/users/:id

Create a User

POST /wp/v2/users

Update a User

POST /wp/v2/users/:id

Delete a User

DELETE /wp/v2/users/:id

Users API Reference

VueJS Theme

In the next couple of weeks we're going to investigate how you can create a WordPress theme using VueJS to access the REST API to replace the PHP version of themes. I'm also going to see if I can replace the existing theme on Paulund and use a VueJS theme moving forward.

Back to top

Learn how to code with Treehouse

  • Learn projects with access to 1000+ videos
  • Practice live with our Code Challenge Engine
  • Get help in our members-only forums

Start with a 7 day free trial