Extending The WordPress REST API

Josh Pollock - July 29, 2015

Remember the first time you got annoyed WordPress didn’t do something, and then you realized with the right amount of Googling, experimentation and foul language, you could probably make it do that?

I don’t exactly, but some how it got me to where I am today, and I’m pretty happy about that :)

Hopefully, we will soon have a RESTful API in WordPress core. Since this is WordPress, the features of the REST API are sensible defaults, designed to work on tens of millions of sites. That means that there will be plenty of cases where the default routes do not fit the exact needs of a site, app, plugin, or theme.

Of course, since this is WordPress, the REST API is highly extensible. I’ve now written two articles on extending the REST API for Torque, and contributed to the docs on this subject.

I’d like to give you a brief overview of how to extend the default routes, and add your own, and show you some examples of plugins I’ve created to do  both. In addition I’ll link to the Torque articles and documentation to help you learn more.

But First

Version two of the REST API is on WordPress.org!

Version 2 of the REST API can now be installed as a plugin from WordPress.org. This makes testing easier. The two versions are separated so those relying on version 1 can continue to do so.

In the future the plugin will provide backwards compatibility for version 1 routes and endpoints, once version 2 has been merged into core. At this time, backwards-compatibility is not complete to version 1, and anyone relying on version 1 should continue to use the version 1 plugin.

The oAuth1 plugin from the REST API team will be available on WordPress.org soon.

Extending The Default Routes

add_filter( 'the_content', ...

WordPress ships with a really comprehensive set of URL mappings, that are all most sites need. But that doesn’t mean that an off the shelf theme, shows all the data you need. That’s why we modify template files, or hook into the_content to show custom fields and other non-standard data.

The REST API comes with a really useful set of default routes and endpoints. But those default endpoints are not always going to show the data you need, or give you the ability to update all the data that you consider part of the post/ term/ user / comment.

The REST API has a really helpful function called “register_api_field” to add the ability to read and/ or write new fields, from custom fields or any other source to an existing endpoint.

I covered using register_api_field, as part of my article for Torque on working with post meta data via the REST API. I actually turned the code examples in that article, showing how to read and write SEO title and description fields via the API into a plugin, which is in beta now, and we will be released at CalderaWP soon.

I wrote a few more examples of using register_api_field in the documentation site for the API. The version 2 docs are coming along nicely BTW. If you are looking for  away to contribute to this project, docs are a great, and needed way to help.

Rachel Backer, co-lead developer of the REST API project gave some examples of how this cool function works during her recent WPSessions presentation, which I strongly recommend watching.

 

Add Your Own Endpoints

$query = new WP_Query( …

The WordPress REST API is not just at the default API routes and endpoints, it’s infrastructure for creating APIs. That infrastructure is really well done. As someone who has rolled my own API on many occasions, I look forward to the day, when I’ll be able to take all of this API infrastructure for granted.

Custom endpoints are really useful for when you don’t actually want to query with a core query tool (WP_Query, WP_Users, etc.) but want to wrap some other function, or class. I’m particularly fond of the fact that I can now create classes for fetching and saving data, and then easily wrap an API endpoint around it.

On thing I love, about custom endpoints is that the API establishes a pattern of separating sanitization, validation, permissions checking, processing and responding into discrete methods in your class. Also, as this becomes the standard, hopefully we will see less misuse of admin-ajax in the front-end.

After writing about creating custom endpoints for the REST API in Torque, an article based on the CalderaWP API, I created an add-on for SearchWP, that allows for using that plugin’s awesome search powers via the REST API. After reading my article, I recommend reading documentation for adding endpoints. It explains how to follow the core API patterns and provides some good, generic example code.

Needs Help Figuring Out What To Do?

I know, it’s a lot

This can be a lot to digest. If you’re getting ready to jump into a project involving the REST API, you may not be sure if you should extend the existing endpoints or add your own. It’s a tough question, and the answer varies from project to project.

If you need help preparing for this type of project, I offer consult calls to sort through these types of questions and provides guidance moving forward. I also love doing custom development with the REST API, especially when I get to write custom endpoints.

Let me know how I can help :)