The WordPress REST API

The WordPress REST API project is the most exciting project for the platform since custom post types were introduced in WordPress 2.9 and 3.0. I really believe that.

While the project is under a major rewrite and not yet slated for a specific core release, it can be really confusing to figure out what’s going on.

Let’s talk about what the new API is, why it matters, and go over the state of the API to answer some common questions I’ve seen.

What is a JSON REST API?

Let’s start by defining the acronyms. It may seem tedious for experienced developers, but it’s a good way to get us in the right mindset.

API: Application Program Interface

APIs have a broad definition. Any program is an API. When you have some form of construct in a programming language — like PHP for example — where the construct makes it possible to perform a programming task, that’s a good way to think of an API.

Let’s use custom post types as an example. WordPress has a custom post types API. Really, it’s just a significant chunk of code that makes previously difficult tasks simpler. Now, you can create all new types of content — that mimic the content structure for posts and pages — with just a few lines of code.

The core team created a programming interface to make that possible. That’s a layman’s definition for an API.

JSON: JavaScript Object Notation

JSON is a preferred format for structuring data so that a variety of applications can read it. You can create JSON formatted data from one programming language and read and process it from another. It’s similar to XML, but seemingly universally preferred over XML.

JSON makes communication between something like WordPress and something like a mobile app completely possible, as JSON is a common data format between them, so that you can create data on the WordPress side and return it in JSON, so that the data can be easily read on the mobile app side. Such relationships don’t have to be between WordPress and a mobile app; it could be nearly anything, meaning “WordPress as an app platform” becomes much more realistic.

JSON looks terrifying if you see it “raw”. For instance, Post Status has the WordPress REST API enabled, so if you go to https://poststatus.com/wp-json/posts you can see my recent posts in a JSON format. This isn’t pretty to the human eye, but for a programming language, it’s beautiful.

REST: Representational State Transfer

A REST API is an architectural preference. Most REST APIs, including WordPress’, are based on HTTP. This means that the primary actions of the REST API are HTTP actions: POST, GET, PUT, DELETE.

So, with a REST API, we are reading or manipulating data using HTTP.

Wikipedia kindly defines RESTful APIs better than I can, namely with a definition based upon the restraints on the API itself:

Web service APIs that adhere to the REST architectural constraints are called RESTful. HTTP based RESTful APIs are defined with these aspects:

• base URI, such as http://example.com/resources/
• an Internet media type for the data. This is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)
• standard HTTP methods (e.g., GET, PUT, POST, or DELETE)
• hypertext links to reference state
• hypertext links to reference related resources^[8]

These restrictions serve as standards that anyone working with a RESTful API can expect to exist. So, in my case, I’m utilizing both the WP API and the Mailchimp API on Post Status. Interacting with either feels similar, because they’ve placed similar constraints on themselves.

What is the WordPress REST API?

Now we know what a JSON REST API is, so we can better define what the WordPress one is.

The WordPress REST API is a common data and programming interface that abstracts the reading and writing of information for WordPress from the WordPress application as we’ve previously known it. Now, developers working with WordPress don’t have to know that much about WordPress.

How can the WordPress REST API be used?

Developers will be able to perform nearly all the data manipulation and data reading functions that are possible with PHP, with the new API. What’s that mean? It means everything.

Ditching WordPress on the front-end

With the JSON API, the frontend of WordPress doesn’t have to be WordPress at all. For example, developers can completely bypass the WordPress templating engine using the API. They can even keep the backend of WordPress and the front-end of the website on completely different server stacks, because they just need to read the data using the API.

There are already many websites doing this around the web. Some of them use custom APIs they built themselves, and others are using the new WordPress REST API. Let’s discuss a couple of examples:

1. The New York Times uses the WordPress REST API for a variety of things. They are able to use the API in combination with their proprietary CMS. This allows them to pull WordPress data for placement on the Times’ homepage and other places very easily. They’re also using the REST API for their live event coverage, like this elections live blog.
2. Bloomberg Politics uses WordPress to publish, but based on the front-end of the website, you’d never know it. I don’t think they’re using the official WordPress REST API, but they could.
3. Mashable uses WordPress to publish, but their front-end is not WordPress at all. This is also a custom implementation, as they made the switch before the official REST API was even underway.

These are three examples of news sites using REST APIs for the front-end. But the applications go much, much farther than that.

WordPress as an application

If you want to see a prime case study, watch K. Adam White’s presentation from WordCamp San Francisco 2014, where he talks about how his team used WordPress as the CMS for a node.js app. This really highlights the potential I’m talking about.

Looking through the resulting ExpressPress repo that K. Adam highlights in his presentation is an educational and fascinating experience.

Custom WordPress admins

WordPress administration doesn’t have to use the WordPress admin as we know it. With the REST API, you can create, edit, and delete content just as well as you can read it.

Eventually, the WordPress admin itself may be re-written on top of the REST API. Using the API, creating completely custom administration panels will be easier than ever before. This will allow developers to create catered administration experiences for a particular application.

For example, WordPress.com has already utilized their own REST API (which will hopefully be a similar implementation to the core API once it’s included) to create a custom admin experience for their blogging platform.

Other services, like Happy Tables for instance, have also created custom WordPress admins. Doing this in the future will be easier than ever because the REST API integrates existing WordPress functionality to the API, so that developers don’t have to reinvent the wheel.

App integrations

Additionally to custom web integrations, WordPress will be able to talk to apps easier than ever before as well.

Previous apps that interfaced with WordPress would most often use XML-RPC. With the REST API, the ability to perform complex functions in a reliable manner is increased. It will be simpler than ever to create a mobile app that can not only read WordPress data, but also  create, edit, and delete that data.

The entire mobile app can be written in Objective-C, Swift, or whatever programming language, and interface with WordPress.

An example of this in action is AppPresser (which I covered when it launched). AppPresser has created an application framework that integrates with the WordPress REST API to make creating WordPress apps for individual sites quite simple.

But it’s not limited to app creation with a tool like AppPresser. People can now have one data-storage area (WordPress) that can power both the website and an app, and that is a powerful feature. Also, the apps can talk to and write to the WordPress database directly through the API.

We will see dozens of WordPress apps and admin integrations over the next few years. We could even see whole startups build apps with WordPress as a base layer.

WordPress can provide an excellent foundation for user management, content management, and much more — reducing the amount of work a startup creating a prototype mobile application have to recreate themselves. The REST API makes it so a mobile app can look completely custom and also use a tool as widely distributed as WordPress to power many of the internals.

When is the WordPress REST API going to be in core?

The REST API is under heavy development, and is also between major versions that will sever backward compatibility. That has made the state of the API confusing.

The REST API hasn’t been slated for a particular release, though it is officially active for the “feature as plugin” model. The goal is for it to hit core some time in 2015, so probably between WordPress 4.3 and 4.5. I’d guess closer to 4.5, as there will need to be a lot of testing once the new stable version comes out.

Keeping up with development

If you want to keep track of the WordPress REST API development, there are a variety of ways to do so, though finding the proper channels can be a challenge at the moment.

First off, know that a major new version is being finalized as we speak, so there is disparity between 1.1.x and the upcoming version for information, code, and documentation. The version under development — and is a significant restructuring — has been under development for nearly seven months.

The WordPress.org official plugin page is somewhat closely synchronized with the latest 1.x release, though it is a few commits behind. The plugin is authored by Ryan McCue, who is the project lead and the initial author of the plugin, as it was his Google Summer of Code project for the first iteration. The WordPress.org page could also use some updating to make it more obvious that it’s the official REST API plugin for the WordPress project.

The WP API Github is where active issue tracking, version management, and releases are being handled. The API has its own account on Github, rather than being a part of the WordPress account, as there are adjacent repos to the actual API and it wasn’t originally guaranteed to be in core.

The key to understanding the various states of the WP REST API is to think in terms of Develop, Master, and Stable versions.

• WordPress.org plugin repository is the Stable version of the WP API.
• Github Master branch is where a Beta version of the next release is managed.
• Github Develop branch is where the active development occurs.

If you’re using the WordPress REST API in production, you should use the WordPress.org version only. The Github Master and Development versions should be used for development and testing only.

Improvements coming in the rewrite

The long development cycle for the new version of the REST API is because it’s a signifcant rewrite for the project.

Based on feedback and real-world use cases, the team was able to identify necessary improvements that needed to happen.

There have been many, many changes in this version, but a couple of big ones are as follows:

• New functions have been added to allow for registration of custom endpoints with namespaces and versions. Rachel Baker shared this gist with me that showcases that. This means themes and plugins will be able to add to and extend the API, offering significantly more power to it.
• Comment creation and edit handling have been added in the rewrite.
• The team has also started work on support for options endpoints to be able to view, edit, and create general site options, which would make complete site management possible with the API, in addition to content management.

The changes in the current development cycle have taken a long time, and have required some significant architectural changes, but are very much worth the long term benefits.

Contributors to the WordPress REST API

There have been 49 code contributors to the REST API project on Github. It’s already a huge community effort. However, there are some folks that are really driving the project forward.

• Ryan McCue: Ryan is the overall project lead, and is generally steering the ship. This all started as his GSoC (Google Summer of Code) project and he is still the lead. He works for Human Made, primarily on Happy Tables.
• Rachel Baker: Rachel is a project lead, and is doing a great deal of development, as well as education and evangelism. She works for 10up as a Senior Web Engineer.
• Daniel Bachhuber: Daniel is in day to day conversations and also commits a lot of code to the project. He works for himself and is the interim engineering director at Fusion.
• Joe Hoyle: Joe is in day to day conversations and also commits a lot of code to the project. He is a co-founder of Human Made.

Though I highlight these four contributors, but there are a whopping 400 people watching the #core-restapi channel in Slack, and there are 49 code contributors on Github. Everyone deserves a huge round of applause that’s taken part in the strategic, code, education aspects of this project.

And this is all before it goes into the core development cycle. Once this gets slated for a specific release, it’s going to get an insane amount of attention to make sure it’s ready for prime time and the millions of WordPress installs out there.

Meetings and blogs for the REST API

The REST API has a standing channel and weekly meeting in WordPress Slack, as well as two blogs you can keep track of:

• #core-restapi on WordPress Slack is where day to day communication occurs, and a feed of commit activity also goes into that channel. The weekly meeting is also here — and is actually held twice per week — at 23:00 UTC on Mondays and Wednesdays.
• The json-api tag on Make WordPress Core is where blog posts about the API go. However, this has been rarely used, and is primarily just for release information.
• Frequent meeting notes and other discussions are posted on make.wp-api.org, which is an 02 blog (P2’s mysterious successor).
• Documentation can be viewed on wp-api.org. It’s important to keep in mind that the docs on the main website are for the stable WordPress plugin, not the Develop branch.

Basics for using the WordPress REST API

The new API will make sense to people familiar with other REST APIs. However, if you are new to such things, even with the documentation you can easily get lost. I know I did.

I will have a lot more resources for members soon, but I’ll try and give a quick intro to reading data now.

The first thing to remember is that it’s very important to know if you will be reading data only or reading and changing data. If you are reading data from your own website, and using it on the same website, you don’t need to worry about authentication. If you are changing, adding, or deleting data, then you need to authenticate with the website you are making changes to.

Let’s show a few simple examples of reading data with GET.

A URL to pull content from Post Status would look like this:

[gist id=c983960972582c6ec2c0 file=”posts.txt”]

To pull content with WP_Query parameters you’re used to, you could do it like this:

[gist id=c983960972582c6ec2c0 file=”posts-with-params.txt”]

To pull content of a custom post type, you can do it like this:

[gist id=c983960972582c6ec2c0 file=”cpt.txt”]

And to pull content of a custom post type with those same WP_Query parameters, it looks like this:

[gist id=c983960972582c6ec2c0 file=”cpt-with-params.txt”]

What you see returned in those URLs is the JSON data we’re going after. Go ahead and put one of those URLs in a browser tab to see the return data.

You can see how the method for grabbing that data feels familiar to using WP_Query for a standard WordPress loop. If you don’t specify a parameter, the defaults to WP_Query will be used.

These URLs return that data, but obviously you’ll want to get that data programatically. You can do this within a WordPress install (or outside) with two common methods: PHP or AJAX.

Handling the data will be similar to handling any other JSON data. I’ll have more on doing this with WordPress at a later date, but in the meantime you may enjoy Josh Pollock’s introduction to using the REST API.

Now, of course, you can query far more than posts, as the WP API website notes, but I just wanted to introduce the concepts.

The API allows you to manage pretty much anything: posts, pages, custom post types, users, media, taxonomies, or even overall site data.

This is just the beginning

Unfortunately, I’ve hardly given a proper introduction to actually using the new WordPress REST API. That will have to wait until another time. That said, you should know have a pretty good understanding of what this project is, what it means for WordPress, and where to go to get started with the new API.

I highly encourage you to educate yourself on this API, as well as experiment with it. You can use the Stable branch in production projects (like I do here on Post Status), but it would be really great to get more people testing and using the API in general so that when it ships with WordPress it will be as good as it can be.