Despite all the hubbub that has been going on about the chronically forthcoming WP REST API, there is one crucial thing that I think a lot of WordPress developers may not fully understand: What the heck does this “REST” acronym mean anyway?

Most WordPress developers understand what an API is — it’s a set of agreed upon methods for different systems to interoperate. But this REST thing, it’s kind of just a buzzword for many of us. If that’s true for you, please keep reading. My goal is to arm you to confidently explain REST to people inside or outside of WordPress and make you confident about how this hallowed “REST API” will teach you about the rest of this “REST” thing.

REST and HTTP. Same basic thing.

At its heart their similarity to HTTP is the appeal of “REST APIs.”

The internet works via HTTP. HTTP is a stateless protocol that has a standard set of methods. Your web browser communicates with servers by speaking HTTP verbs like GET and POST to servers configured to respond to them in certain ways. If you’re just browsing a site like WPShout, your browser will have sent a GET HTTP request to our server, and have received back from WordPress the HTML you’re seeing. If you submit a form on the internet, that data is usually transmitted via an HTTP POST request.

I know what you’re thinking: “But David, I came here to learn about REST. I know what HTTP is.” But I bring up the context of HTTP because at its heart their similarity to HTTP is the appeal of “REST APIs” or “RESTful interfaces” (the two are basically the same and I and others may use them interchangeably). What makes people like REST is that they already understand the basics of HTTP. Request are made with a specific verb, and responses are received back by the calling client.

What’s REST? Representational State Transfer

“Hey, a lot of APIs are pretty complicated and confusing. We’ve already got this pretty good API called HTTP. Let’s use that to make better APIs. They’ll be more predictable, and comprehensible, and everyone will love them.”

So we’ve established that REST is like HTTP. But what does the acronym mean? What is Representational State Transfer? Why the big long name? I thought of trying to break it down word-by-word, but to be honest I can’t and it probably wouldn’t be useful if I could. So instead let me tell you some very small quantity of relevant history.

The name “Representational state transfer” in this sense comes from a guy named Roy Fielding. In his PhD dissertation, Mr. Fielding basically said “Hey, a lot of APIs are pretty complicated and confusing. We’ve already got this pretty good API called HTTP. Let’s use that to make better APIs. They’ll be more predictable, and comprehensible, and everyone will love them.” (Although I put quote marks around that, I have no evidence that Mr. Fielding talks that way or ever said those words in that order.) In any case, with time people saw his wisdom and so there were REST APIs.

What are REST Resources? Routes?

To my mind, there are two core parts of a REST API: that you have resources (which you could call entities, or objects, or something else) and that you act on those resources via standard HTTP requests with standard HTTP verbs. To understand resources, you must understand that REST APIs are organized around URIs — uniform resource identifiers — and that generally those are centered around these entities. To stop using abstract words, for the WP REST API the entities you’ll certainly recognize are currently: posts, pages, media, comments, categories, tags, and users. There are a few other more abstract ones you may also be comfortable with: post statuses, post revisions, taxonomies, and post types. The idea is that each of these resources lives at a specific URL.

If you want to see the posts from a WordPress site which is currently running the WP REST API plugin, you can go to www.example.com/wp-json/wp/v2/posts/ and you’ll see the raw JSON from that site’s most recent blog posts.

In general, a REST API will live relative to some root. In the case of the WP REST API, that root is your WordPress site’s URL — say wpshout.com — followed by /wp-json/wp/v2/. So all resources will be at “routes” relative to wpshout.com/wp-json/wp/v2. So the post resource lives at /posts/, that could be said to be that resource’s “route.”

What that means is that if you want to see the posts from a WordPress site which is currently running the WP REST API plugin, you can go to www.example.com/wp-json/wp/v2/posts/ and you’ll see the raw JSON from that site’s most recent blog posts. And to get to a single entity, you just add its ID to the route. So to see the post with the ID of 1111, you’d go to www.example.com/wp-json/wp/v2/posts/1111.

Standard REST Verbs: GET, POST, PUT, PATCH, DELETE

While there are technically 9 HTTP request methods (what I’m calling verbs) I’ve only ever seen five implemented to do actions with a REST API. This is basically because REST methods map pretty well to “CRUD.” CRUD is a common acronym which stands for create, read, update, delete — the four obvious operations that one wants to do with a piece of data. Four operations don’t need 9 request types. But there is one extra.

In any case, the five HTTP methods on most REST APIs are:

• GET which is used for reading data. GET requests — inside and outside of REST contexts — are considered “read only.”
• POST which is generally used for creating new data. Sometimes POST is used for updating too, but generally “best practice” says to use…
• PUT or PATCH for updating data. Why two? Because sometimes you want to replace it completely — when you PUT — and sometimes you just want to replace or change a value of two — when you PATCH. Update operations are kind of the least standardized in practice, because support for PUT and PATCH isn’t as universal as GET, POST, and DELETE.
• DELETE is for deleting data. Hardly seems worth a sentence of explanation.

Tying Verb to Routes for Great Victory

Here’s the basic story of how you’d use the WP REST API to do some common WordPress operations. Likely you’d make other requests, but this story highlights the most important parts of REST.

1. GET to /posts/ to see a list of all posts.
2. POST a bunch of data about a new post to /posts/ to create a new one. It’ll give you back the post resource that you just created with its ID. For simplicity, let’s say that ID was 123.
3. POST to /posts/123 to update your just-created post. (PUT and PATCH are more “correct” than POST, which is why we specified them above. The WP REST API is using POST because it’s a lot less troublesome with PHP and various server configurations than the other two.)
4. GET to /posts/123 to see your just-completed post.
5. DELETE to /posts/123 because you just realized that post wasn’t very good and don’t actually want it.

Make sense?

Other Considerations: Data Formatting, Authentication, and Other Functions, Oh My!

I hope so far you feel more clear about what REST really is and means. But we’ve only started to scratch the surface of quite a deep area of study and practice. So before we depart, I want to include some parting things that come up as you get deeper into REST APIs.

JSON: One Format to Rule Them All?

REST APIs as a term, however, has no requirement that they speak JSON. REST XML APIs are common.

Though the project goes by the moniker of “WP REST API” the fact that the plugin and final representation as it land in WordPress core is likely to be JSON-only is notable. It’s most common for REST APIs to talk JSON — for the uninitiated that’s a data format with lots of curly braces, some square brackets, and dictatorial adherence to strict comma counting.

REST APIs as a term, however, has no requirement that they speak JSON. REST XML APIs are common. Also quite common are REST APIs that can talk XML and JSON, and sometimes even more formats. For WordPress, this isn’t likely to happen. But it’s pretty common elsewhere.

Authentications — knowing who someone is — is complicated…

HTTP and REST are “stateless” protocols, the exact meaning of that isn’t super and important, and to be completely honest I’m not sure I understand it well enough to explain it. The core thing it means is that browser send “cookies” to fake “state” — knowledge of a user and continuity for their data — in most server-based applications. This cookie-hack works for browsers, but when another (REST API, for example) layer gets involved, things get harder.

The short version of what this means is that you think harder about a authentication strategy when talking to a REST API than when dealing with a basic WordPress site. Terms like “Basic Auth” and “OAuth” come up a lot if you try to do anything more complicated than reading data from a REST API. Just a thing to know.

Complicated Operations with REST can be weird…

A lot of REST is pretty great. But because the whole idea is oriented around “CRUD” operations, slightly more complicated operations become complicated to consider. For example, if a user is removed, and I want to remove all the data they created, do I do that by hand with 8000 different DELETE requests to the REST API on each resource they own? Or should an operation which sends a DELETE to /users/7 always remove their associated data? The answer isn’t clear.

Most data entities have attached entities with their own data. Should a response to GET /posts/123 include all the data about the categories on a post, or should the requester have to make another request to GET /categories/71 to know more about the category?

This also says nothing about wanting to be able to trigger an application to do complex operations — say scan all blog posts for typos — which aren’t themselves resources, but instead touch hundreds of different ones when performed. Again, there’s no universal standard or “right answer.”

Finally, most data entities have attached entities with their own data. Posts have categories in WordPress, for example. Should a response to GET /posts/123 include all the data about the categories on a post, or should the requester have to make another request to GET /categories/71 to know more about the category?

These aren’t issues every application with a REST API faces, but they’re common enough to keep in mind when thinking about the term and its implementations.

The JSON REST API Continues to Excite

It’s still not clear when the WP REST API will all be inside of WordPress. Eighteen months ago I said it might come in 4.1. Nope. Today all I’ll say is that we’re sure it won’t happen in WordPress 4.5, which is landing soon. Whenever it does happen, a lot of high hopes will finally start to butt heads with reality. It’s an exciting thing we’ll see.

Hopefully you understand some of the core ideas of REST better now. And it makes some sense why people are so eager to have the REST API in WordPress. Whether you only ever use other plugins, themes, or apps which use the REST API, or if you build your own applications which make use of it, it’s certain to touch your future with WordPress. Happy hacking!

Image credit: Ilham Rahmansyah | Unsplash, Kevin Gessner