An introduction to the WordPress REST API

Be sure to get plenty of REST

There’s a buzz amongst the WordPress community, and that’s the full inclusion of a REST API into the core code of WordPress. If that sounds like geek speak, it surely is… but I’ll explain why it’s exciting.

With WordPress 4.4, adoption of a fully functioning REST API will be included in the core code of WordPress.

What’s an API?

When you are accessing WordPress via its administrative panel, you’re accessing a user interface. That is, you utilize the system through visible forms and use mouse clicks to navigate. If you wished to program another system to perform the same functionality, it’s difficult. However, Application Programming Interfaces were built for just this reason. Utilizing an API, a developer can program automated functionality to a system.

What’s a REST API?

REST stands for Representational State Transfer. That explains a lot, doesn’t it? In simple terms and with respect to API services on the web, REST simply means that you request information from a web address, and it sends information back, often in a machine-readable form. This response can then be used by other programs.

Nicely built REST APIs offer you the opportunity to request both the format of the data as well as the information requested.

Here’s a great example from freegeoip.net, a community-funded service that provides location data for a given domain or IP address:

A request is made to freegeoip.net (without authentication) with one of the three most common formats — CSV (comma separated values), XML (Extensible Markup Language), and the very popular JSON (JavaScript Object Notation) format.

Examples:

Perhaps you have a website where you want to dynamically display specific information based on the location of the visitor. You can pass the user’s IP Address (here’s how) via the API call and then display the content meant for each location.

The WordPress REST API

The plugin that enabled a REST API in JSON format has been in the repository for quite some time and is installed on more than 10,000 sites. Why would anyone wish to use a REST API with WordPress? Here are some quick examples:

Automated Posts — You have a weather tracking program that generates an alert for a tornado warning or watch. An API would enable you to program a WordPress site to automatically publish a post when an alert is triggered.

Syndicated Posts — You have a mobile application where you wish to syndicate content, but there’s more data that’s included in a typical RSS feed. Perhaps you have custom event data, for example. An API would enable the mobile platform to authenticate and request the data from your WordPress server to update your mobile application.

Authentication — You have a WordPress site, bbPress forum, BuddyPress social network, or WooCommerce e-commerce instance where all of your users are setup and configured. Perhaps you have a third-party application that you’d like to authenticate using the WordPress account. Being able to utilize the API eliminates the need to have users having multiple logins to multiple systems. Tim Nash has working code and examples on his WordPress REST API Authentication examples post.

In other words, pulling information, pushing information or authenticating are all possible, programmatically, from outside your WordPress site! Eventually, core WordPress features will be accessible via the API.

WordPress is becoming a framework, not just a content management system.

 

Today, many developers use a plugin to work with WordPress using an API. Developers can access WP Query, the posts API, post meta API, users API, revisions API, taxonomies API, and other capabilities in this way. You can find additional info on the plugin documentation site.

Examples

  • Retrieve Posts — Send a GET request to /wp-json/wp/v2/posts.
  • Update User — Send a POST request to /wp-json/wp/v2/users/1 where 1 is the User ID.
  • Query Posts — Get all posts with the search term “technology”? Send a GET request to /wp-json/wp/v2/posts?filter[s]=technology.
Theme and plugin developers can replace their own endpoints with the REST API endpoints in WordPress.

 

Currently, if you’re a theme designer or plugin developer, you create your own endpoints where you request and push data in WordPress 4.4. Depending on your development style, these endpoints can differ greatly in the method used or its location. Exposing the API for usage in themes and plugins will provide consistency for passing data via the API endpoint and removing unnecessary endpoints.

Note: The endpoints still require the WP REST API plugin while the API is being fully integrated into the core code. Future versions will not require the plugin.

WordPress REST API examples

The REST API has been around for quite some time in plugin format, so you’ll already find some robust examples of use out on the web:

If you want to learn more about how to work with the WordPress API in its current state, Delicious Brains has a solid primer. And if you want a deeper read on the future of the WordPress API, check out this post on make.wordpress.org.

Image by: smellslikeupdog via Compfight cc

Douglas Karr
Douglas is a marketing technology expert, working with key industry players, corporations and startups for over a decade. As the CEO of his consultancy, DK New Media, he consults and develops strategies for assisting marketing technology companies gain market share as well as enterprise corporations with vendor selection. He advises investors and venture capital firms. He's also been integrating, developing, and optimizing WordPress since version 1.5 when he founded his Marketing Technology blog.