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.
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:
- Where is Godaddy.com located? XML Request:
- Where is Godaddy.com located? JSON Request: https://freegeoip.net/json/godaddy.com
- Where is Godaddy.com located? CSV Request: https://freegeoip.net/csv/godaddy.com
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.
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.
- 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.
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:
- Reactor — allows you to build fully functioning mobile applications with your self-hosted WordPress instance.
- Event Espresso — event registration and ticketing management for WordPress.
- Focused on Fit — an online community with a mobile app that works with the WP REST API.
- Simmer — Develop recipe apps on mobile, web or alternative UIs.
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.