THE WORDPRESS REST API: WHAT IT IS, WHY IT MATTERS, AND WHAT YOU NEED TO KNOW ABOUT ITEVAN VOLGAS

“Chances are, if you can do it with WordPress, the WP REST API will let you do it.”

— the WordPress REST API (Version 2) Plugin documentation

What is an API? Why do we care about them?

An API is an Application Program Interface

Consider a soda machine

It has an interface

Users authenticate and submit requests through the interface

The machine sends users responses

An API is a fancy word for “making it easier for this bit of software to work with that other bit of software so that they can both do stuff together”

There are several APIs in WordPress that you probably already use (whether you realize it or not)

Database API: Allows you to interact with the wp_options table in MySQL by way of add_option(). Also deals with transients and metadata in WordPress.

Shortcode API: Allows you to register WordPress shortcodes via add_shortcode()

Plugin API: when you install a plugin, that plugin "hooks" into the rest of WordPress via the Plugin API

Rewrite API: Manages writing your WordPress URLs for you. When you go to Settings —> Permalinks in your dashboard and specify a permalink pattern for your pages and posts, those settings are applied to WordPress by way of the Rewrite API

HTTP API: Allows you to have WordPress submit HTTP requests to other servers (for example, when you upgrade WordPress from your admin area, WordPress is submitting an HTTP request to WordPress.org by way of the HTTP API)

There are about 15 APIs in WordPress today. What’s so special about the WP REST API?

The APIs that we've talked about have to do with WordPress interacting with WordPress. For example:

Having WordPress add a setting to the WordPress database in MySQL

Adding a WordPress plugin to your WordPress website

Registering a WordPress plugin with your WordPress website

Having WordPress rewrite WordPress's urls

With the exception of the XML-RPC API, none of WordPress’s API have to do with interacting with other, non-WordPress software AND vice versa

WordPress’s XML-RPC APIThe XML-RPC API was added to WordPress in version 2.5 (March 2008)

Requests to this API are sent in an XML formatSample request: http://codex.wordpress.org/XML-RPC/wp.getComments#Example_Request

Sample response: http://codex.wordpress.org/XML-RPC/wp.getComments#Example_Response

Clients that interact with the XML-RPC API have to tell WordPress which method to apply in order to fulfill their request

What this means in practice is that developers have to understand WordPress and the WordPress XML-RPC API in order to use it

Remember the soda machine: instead of pressing a button for Super Sugary Soda, you’d have to issue something like a soda.dispense(option=4, quantity=1, change=0.25) command to the soda machine

Access credentials passed to this API are unencrypted

What this means is that SSL is required if you want to use the XML-RPC API in WordPress (otherwise people can sniff your credentials from the network)

REST-ful APIs for the rest of us

REST = REpresentative State Transfer

It’s not a specific tool or framework; it’s more just a way of thinking about things

There are a handful of specific properties an API must have in order to be considered RESTful; for our purposes today, the most important of these properties is statelessness

Statelessness boils down to the idea that everything a server needs in order to handle a request must be contained within the request itself. Put another way, the server is not allowed to share information between requests (this is why browser cookies are a thing, if you’ve ever wondered)

Because the server can’t share information between requests, every resource (for example, a page, a post, etc) you want to expose through your API must have a unique Uniform Resource Locator that can be specified in an individual request (a URL for example, or a URL in combination with some query strings)

The WP REST API: Remind me again, why does this matter?

Comparison: REST vs XML-RPC

Let’s look at that comments requests again:

https://gist.github.com/evanv/8fca368c81f825bdd26570867bd4fd4b

Let’s look at those responses:

https://gist.github.com/evanv/75f5523b8bc48befcd8c2c46cb505d50

The first thing to note is that the requests and responses of the REST API are understandable, even if you don’t know a thing about WordPress

The WordPress REST API: Who cares if it’s easier to work with?

Regardless of which API is “better”

REST and JSON are widely understood both by programming languages and by programmers (and even, arguably, non-programmers)

HTTP, too, is well understood and widely supported

XML… not as much

WordPress’s XML-RPC API requires developers to know something about WordPress and the XML-RPC protocol in order to use it

Depending on what software you are using, XML-RPC support may be poor

It is very likely to be more complex dealing with XML-RPC than it would be dealing with HTTP requests and JSON, no matter what language you’re using (don’t take my word for it: try submitting an XML-RPC request to WordPress, then try submitting one through the REST API)

“Chances are, if you can do it with WordPress, the WP REST API will let you do it.”

That’s true… but that’s also not really the point

“Chances are, if you can’t do it with WordPress, or if you can’t do it very well, you can use whatever

tool you want. And integrating that tool with WordPress is going to be a heckuva lot easier now,

because of the WP REST API”

—Julien Melissas*(okay maybe he didn’t actually say that)

“Not just a blog”You’ve probably heard the saying, “WordPress is not just a blog.”

It may not be long before you start hearing people say “It’s not just a CMS either.”

Because of the WordPress REST API, we can start thinking of WordPress as a web application framework, not just a CMS

You can extend the WP API with new endpoints

You can use it, both inside of WordPress/PHP/JavaScript and completely outside of it (Python, Ruby, Java, Go, whatever)

You do not need any esoteric knowledge of XML-RPC in order to use the the WordPress REST API; it’s as simple as working with HTTP and JSON

Modern Web Applications vs WordPressLook at Facebook / GitHub / StackOverflow / Amazon / etc

All of these websites manage content, users, user permissions, sign up and login, password resets, email notifications, and so forth

What makes them web applications (instead of simple content management systems) is they have a whole fleet of software extending them beyond simply the content they contain

Recommender systems and customer analytics

Mobile apps

Domain-specific services (ad targeting, relationship mapping, organizational membership, etc) that are exposed via RESTful APIs

WordPress as a web application

The REST API places WordPress inside a much wider ecosystem of software

Some of that software might excel in areas where WordPress/PHP/ JavaScript are relatively weak

If you come across something that you can't do with WordPress, or that you could do much better with some other software, the WordPress REST API makes integrating that other software with WordPress - and finding developers who can do that work for you - much much easier

The WordPress REST API: Where is it and where is it going?

The infrastructure for a REST API was added to the core in Dec 2015 as part of the 4.4 release (think of this as all the mechanical stuff inside a soda machine)

The actual API endpoints require the use of a plugin (https://wordpress.org/plugins/rest-api/) (the endpoints are kind of like the parts of the soda machine that you as a human being actually interact with)

Later on, these endpoints will be merged to the core (WordPress 4.7? 4.8?)

Is it safe to use the WP REST API on my site?

Yes…

Open up your terminal and try the following commands

curl -X DELETE https://evan.is/wp-json/wp/v2/posts/725

curl -X POST https://evan.is/wp-json/wp/v2/posts/725 -d ‘{“title":"Hey you told me this was safe!”}'

curl -X GET https://evan.is/wp-json/wp/v2/posts/725

What can I do to get involved with the WP REST API and how can I start taking advantage of it?

How do I get involved with the WP REST API?

Contribute: https://github.com/WP-API/WP-API

Follow along: https://make.wordpress.org/core/tag/json-api/ and the core-restapi channel on the WordPress Slack Channel

Learn a little bit about REST: http://www.restapitutorial.com/

Think of something that WordPress is bad at and figure out how to make it work with WordPress (and then do the same thing but the other way around)

Install the WordPress REST API on your site and play with it: https://wordpress.org/plugins/rest-api/

QUESTIONSWORDCAMP ASHEVILLE 2016