Extending The REST API Talk

My fall 2015 WordCamp talk is on extending the WordPress REST API. I love doing tweaky server-side PHP development, so I fell in love with the REST API, and even more with the extending it. I’m excited to be giving this talk a few times and hope to have video of it up soon.

You can see my slides, video from the talkm and a helpful list of links below.

By the way, did I mention I wrote a book on the REST API? Well I did, and it’s both awesome and free — thanks to the good people at Torque and WPEngine. You can down download it here.

In my talk I give an introduction to extending the REST API by modifying the default responses and creating your own endpoints. If you’re like me, and learn by reading code, I recommend checking out these two plugins I wrote:

  • SEO REST API Fields This plugin exposes SEO fields for WordPress SEO by Yoast in post endpoints, and allows for updating them along with the post data.
  • SearchWP API This plugin adds a custom endpoint for doing advanced queries, powered by SearchWP — an amazing WordPress search plugin — using the REST API.

I wrote a post a few weeks ago on the topic of extending the REST API, with more links to docs, and articles I wrote for Torque. Be sure to check that out.

 

Extending The WordPress REST API

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 :)

Why The WordPress REST API Must Be In Core

Recently I sat down with the developer of Morning Frame, a really cool analytics integrator, to help him figure out how to integrate with WordPress. I had to explain, as best as I could, the difference between the WordPress.com API, the Jetpack JSON API module, and the WordPress REST API.

Explaining, to someone with little experience of WordPress, the subtleties of how the WordPress.com API relates to the Jetpack JSON API module, and how the real one is the one that’s in a plugin, but it’s in a feature plugin, which is…

Yah, it got confusing.

The WordPress REST API has seemed like a forgone conclusion for inclusion in WordPress 4.4. Matt Mullenweg highlighted the REST API in his last State of the Word and all of the wonderful possibilities it could bring to WordPress.

While there has been ambiguity, it’s the topic that everyone wants to discuss at WordCamps. It’s the only reason why application developers from all sorts of backgrounds are looking at WordPress as the back-end for their apps. And the API itself the code is really beautifully with really lovely extensibility. It’s also in use on high traffic sites, has a dedicated team of “core” team of developers, 50 some minor contributors and is almost ready to go.

API Wapuu by Michelle Schulp.
This Wapuu by Michelle Schulp is adorable. Don’t break its tiny heart.

The seaming unavoidability of this becoming a feature of WordPress was snapped on Monday, when, during an epic 6 hour Slack conversation. During that conversation, Matt voiced his concerns about it, and questioned whether this feature should be a feature at all or if it made sense to stay as a plugin.

Nothing is settled, and no decision has been made one way or another, but now is the time to speak up if this feature is important to you and if you’re reading this site it almost certainly is.

I have no idea what is going to happen. I suspect, but have no idea, that Matt is playing devil’s advocate and challenging everyone to question their assumptions. Questioning assumptions is an important part of decision making. If that’s what is happening then he is being a good leader.

I followed the whole discussion, as this really important to me. I also built, yet another REST API add-on while I was reading, this time for WordPress SEO by Yoast :)

Having read the discussion, I am even more convinced that the REST API has to go in core. It’s a feature we need.

Either a RESTful API is a feature of WordPress — and it should be — or it’s not. And if it’s not, that’s a potentially devastating mistake for WordPress.

I wanted to share a few important reasons why I feel this way. I hope ya’ll will agree, and more importantly, share your own reasons why, either in a comment — now powered by Postmatic :) — or on Twitter or write about it on your own blog.

Update: An excellent place to share how you’re using the REST API and why it is important to you to have in WordPress core is in the comments on this make post: https://make.wordpress.org/core/2015/07/23/rest-api-whos-using-this-thing/

Now is the time to share why we need this feature in WordPress.

There Is No Existing Solution

XML-what?

Curiosity Mars Rover (From Wiki Commons)
NASA put a robot on Mars, we can put an RESTful API in WordPress.
Image via WikiCommons

All modern web apps, and most websites need a public-facing API. XML-RPC does not solve that requirement. XML is not modern, developer friendly or efficient. It’s also not what modern MVC frameworks consume.

One of the goals of the WordPress REST API project is to allow the phasing out of XML-RPC in core. A plugin can’t do that.

The modern web is being built with frameworks that consume JSON APIs. WordPress’ content editing tools, plugin ecosystem plus a RESTful API that is a huge boost to application developers.

Seriously this is 2015, RESTful APIs are what we use.

Yes, Jetpack offers a RESTful API, but while I am a big fan of Jetpack and use it on this site, I’m not going to run it on a site that powers an app. Nor is it extensible.

The Jetpack/WordPress.com API is awesome for the integrations with WordPress.com that it offers. But it’s not a developer’s tool.

More importantly, what I learned from working in the WordPress ecosystem is the importance of controlling your own data.

And the REST API can’t be a feature plugin forever, because then its not a feature. It’s another plugin. A feature plugin is a thing that only insiders understand. Beyond that, a feature plugin is a test for a new feature, not a feature. An exciting new feature that never leaves development, that reflects poorly on us all.

It Will Grow WordPress’ Marketshare

The WordPress REST API could democratize application development.

Only a REST API in core can dramatically grow WordPress’ marketshare by bringing app new developers into our ecosystem.

I get emails from non-WordPress developers several times a week looking for help integrating WordPress with whatever they are building. I’ve worked on projects where I didn’t know the language the actual product was being written in or didn’t even know what language it was.

Those emails from developers outside of our ecosystem, looking to use WordPress for their apps, they are coming because the REST API will be in core. If that doesn’t happen then the feature will be seen as rejected — and with good reason.

Growing WordPress’ marketshare, by making a better blogging platform and website builder to compete with Wix or Squarespace brings more users into the pool of users that may need my services, or buy my products. The same goes for most people reading this.

Walking away from having a RESTful API, and an incredible tool for building your own in WordPress is walking away from another set of potential users — developers. These are people who will need the services of qualified WordPress developers, a managed WordPress host, and the various services — backup, anti-spam, etc. that are provided by members of our community.

Having WordPress’ content management system available, for free, to app developers saves them tons of time and money. It means a quicker path to MVP, opening the door to more experimentation as well as a lower barrier to entry for those without financial resources.

The only suitable alternative is to roll your own RESTful API, which we all do. It’s a waste of time, and doesn’t contribute to a standard. WordPress’ job is to create a standard, sensible defaults, and the opportunity for customization. This is what the REST API does — gives us a set of well-done defaults and the tools to customize the API to fit our needs.

Plugins don’t codify standards for the WordPress way and they don’t give WordPress its common defaults — that is what WordPress does.

 

The sky. Photo by: Garrett Carroll
This is a beautiful photo of the sky. Beautiful things are important. Photo by Garret Carroll via UnSplash.

It Is Not The API Until It Is In Core

It’s either a feature of WordPress or it’s not.

Yes, the REST API could just be a plugin, technically speaking. But then it’s a plugin. It’s not a feature of WordPress.

Jetpack isn’t the social sharing, analytics, contact form, etc… plugin. It is a popular option. That’s fine, we don’t need standardization for what Jetpack does.

We need standardization for default routes. There is no other way someone can build a general app, one designed to integrate with any WordPress sites, unless there is a standard. By general apps, I mean content editors, backup and site management systems, all of which are rolling their own APIs right now.

I also mean the kinds of apps that don’t really exist yet, but I would love to build, that work across sites to improve management of specific features — social integrations, SEO etc. Seriously I have a lot of these ideas, someone DM me on Slack or Twitter, if they are interested in getting involved. Well, if the idea of a RESTful API as a feature of WordPress isn’t killed off that is…

It’s also very hard for plugins and themes to integrate with a feature of WordPress, that isn’t a feature. WordPress doesn’t have a plugin dependency system, it may one day, but that’s technical challenge that is going to take a lot of work.

The WordPress theme repository prohibits themes that rely on a plugin to work. There is a good reason for that: a theme should work with WordPress and shouldn’t bork a site if a plugin is disabled.

The REST API presents an opportunity to make better, more dynamic and offline-friendly themes. Until developers can deliver a REST API-powered theme that just works with WordPress it’s not going to be a smart business move for anyone to make.

There is a reason why there are very few WordPress themes powered by the REST API, and none are aimed at “regular users.” Nor should there be, a theme should work with WordPress, not be reliant on a plugin. A REST API-powered theme for general release is a non-starter unless the REST API is a feature of WordPress.

The REST API Has Institutional Support

A new feature is like a puppy, it’s cute now, but what happens when it shits on the rug?

My dog Josie begging in my kitchen.
This is my dog Josie begging for food in my kitchen. Don’t make me beg.

Most new features of WordPress, in some way are useful to WordPress.com, or some other Automattic product. That’s great, as Automattic, a large, stable, and well funded company has an interest in seeing these features maintained.

But WordPress.com already has a RESTful API, this new API is for the rest of us. Luckily WordPress is bigger than WordPress.com.

The WordPress REST API is in use on the sites of huge media outlets. These sites are developed by some of the best WordPress developers — developers with a strong history of involvement in our community.

TheWordPress REST API is in use on sites built by the big WordPress development agencies. The same agencies that contribute in a multitude of ways to our community.

This feature, developed by community members, a part from Automattic, a part from the core team, if it enters core, is a victory for the ideal of an open source community. If this project with an overwhelming amount of support doesn’t become  a feature of WordPress, what does that say about the openness of the WordPress project.

If the REST API is added to core, that is a lot of code that needs to be maintained. Code that needs to work with WordPress 5.7.

The WordPress API has passionate contributors, who will love it when it stops being shiny and new, because they love it and have a vested interest in it continuing to work.

It’s also really well done, easily verisonable, and has great unit test coverage. It’s not perfect, but it can be easily evolved and improved, which will happen if the excitement isn’t robbed from this project.

I Love It? Can We Keep It?

Forget the #wpdrama this is the debate that matters!

I’m not going to lie. I’ve got a lot of skin in this game. I’ve been writing a lot about the REST API for Torque, and building custom add-ons as well as contributing to the REST API docs. I do this because I want to spread the word and because I want to be a go-to person for REST API integration and customization. That’s how free software works — we contribute, create extra tools and educate — giving freely to establish ourselves as experts.

But we all have skin in this.

The WordPress REST API is already attracting new people to WordPress. Adding it to core will bring more. Rejecting it as a feature of WordPress says WordPress isn’t developer friendly.

Even if you never build anything with the REST API — those new people may be your customers or clients.

The WordPress REST API already helping us build awesome stuff. With it in core, we will build even more cool stuff. Rejecting it says “sorry no thanks.” It says we’re stuck in our ways and against modern trends in web development.

Even if you never build anything with the REST API — you are likely to use something built with it.

#wpapi4thefuture

I Use The REST API Because It Is Awesome. Hashbrown no filter.

If you’ve read the source for the WordPress REST API, and I have read most of it, it’s something you can be proud of having in the tool you use to make your living. If you’ve used the REST API, you know how awesome it is, and all of the possibilities it opens up.

We can’t walk away from this feature now, and that’s what happens if it’s not in core. If it’s not in core, it’s just another plugin — not a standard that can help us stop rolling our own APIs, or using XML-RPC.

It goes in core or it’s not something we can all count on being there and count on staying there. If it’s not in core, we’re going to be making insanely complex explantations to potential clients and users for years to come, and apologizing for something we could have had but didn’t.

We were all told the REST API was the future. Then we tried it and said “the future looks awesome.” Let’s not let go of that future.

Access Control Headers For The WordPress REST API

Sending headers, including cross-origin (CORS) headers has changed a bit in version 2 of the WordPress REST API. Access control headers are sent by the function rest_send_cors_headers(), which is hooked to rest_pre_serve_request. You can easily change the headers by unhooking that function, and adding your own.

Below are some examples using access control headers, but really any type of header could be added here. That said, keep in mind that the class WP_REST_Response, which should be used for all responses, also gives you the ability to add headers. Any headers unique to a request should be set there.

/**
 * Use * for origin
 */
add_action( 'rest_api_init', function() {
    
	remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
	add_filter( 'rest_pre_serve_request', function( $value ) {
		header( 'Access-Control-Allow-Origin: *' );
		header( 'Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE' );
		header( 'Access-Control-Allow-Credentials: true' );

		return $value;
		
	});
}, 15 );


/**
 * Only allow GET requests
 */
add_action( 'rest_api_init', function() {
    
	remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
	add_filter( 'rest_pre_serve_request', function( $value ) {
		$origin = get_http_origin();
		if ( $origin ) {
			header( 'Access-Control-Allow-Origin: ' . esc_url_raw( $origin ) );
		}
		header( 'Access-Control-Allow-Origin: ' . esc_url_raw( site_url() ) );
		header( 'Access-Control-Allow-Methods: GET' );

		return $value;
		
	});
}, 15 );


/**
 * Only allow same origin
 */
add_action( 'rest_api_init', function() {

	remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
	add_filter( 'rest_pre_serve_request', function( $value ) {
		header( 'Access-Control-Allow-Origin: ' . esc_url_raw( site_url() ) );
		header( 'Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE' );
		header( 'Access-Control-Allow-Credentials: true' );

		return $value;
		
	});
}, 15 );


/**
 * Only from certain origins
 */
add_action( 'rest_api_init', function() {

	remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
	add_filter( 'rest_pre_serve_request', function( $value ) {

		$origin = get_http_origin();
		if ( $origin && in_array( $origin, array(
				//define some origins!
			) ) ) {
			header( 'Access-Control-Allow-Origin: ' . esc_url_raw( $origin ) );
			header( 'Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE' );
			header( 'Access-Control-Allow-Credentials: true' );
		}

		return $value;
		
	});
}, 15 );


I have a plugin for setting CORS for GET requests and a plugin for setting CORS for ALL requests on Github.

WordPress Search, Custom API Endpoints, Woo!

Yesterday I published a post on Torque about extending the WordPress REST API & released a beta version of a plugin that extends the REST API for SearchWP queries. This new plugin not only gives a great example of how to extend the API, but frankly I think it is a also a better way to run queries then the default routes.

I’m not criticizing the design of the core REST API and its developers. In fact, the such a super-awesome job on version 2 is why its so easy to add a new endpoint like my SearchWP API add-on plugin does. My new SearchWP add-on plugin lets you run meta queries, taxonomy queries, and date queries, and uses SearchWP’s pre-indexing to improve performance. Because of those capabilities, I think it is a vastly superior way of working then the basic route.

SearchWP API, by CalderaWPYou can check out this plugin and get all the details over on the CalderaWP site. If you’re excited about the REST API — and who isn’t — I really hope you will check out its source, the source for the CalderaWP products and documentation API we’re running on our site and the article on Torque.

My goal here is not to show off how I made some cool API add-ons, though I really do love making custom APIs.

My goal is to get developers to stop looking at the default routes as the totality of the REST API, as if it was just one API. Instead, see it as a tool for building your own APIs. Kind of like how the WP_Query class makes WordPress’ default, front-end behaviors work, but we also use it to create our own queries all the time.

WordPress Tallahassee Meetup: Turning WordPress Sites Into Web & Mobile Apps

For the second meeting of the Tallahassee WordPress Meetup I am presenting on solutions for turning WordPress sites into mobile apps and using WordPress as the back-end for a web and/or mobile app. This is a subject that I’ve thought a lot about as I work with the WordPress REST API, and my own projects.

Below you can see my slides and a list of helpful links:

Links From My Presentation:

 

 

Using The New WordPress REST API: Tally Code Camp 2014

Today I will be presenting at Tallahassee Code Camp 2014 on WordPress’ new RESTful API. My slides are embedded below:

Be sure to read my articles in Torque for more information on using the WordPress Rest API.

Frequently Asked Questions

Is This A Plugin, A Feature of WordPress or What?

Over the last two years, most big features of WordPress have been developed as plugins before being merged into WordPress itself. Right now the API is a plugin, that will *hopefully* be merged into WordPress core in version 4.1 or 4.2.

It is totally functional and committed to not breaking backwards compatibility. The “plugin as a feature” development model has a lot of advantages over working with patches to core only, One of those advantages is that you can easily use the feature while it’s under development. The other is that even if it doesn’t make it into core, it can still be used as a plugin.

Isn’t It Part of JetPack?

JetPack has its own RESTful API. Here’s a good slide breaking down the pros and cons of the JetPack API. JetPack’s RESTful API runs on WordPress.com’s servers, which may or may not be a good thing, depending on your needs and worldview on decentralization. The fact that it doesn’t work for local development is a big issue for me.

Is This Going To Replace XML-RPC In WordPress?

Yes and no. I doubt XML-RPC is going anywhere as WordPress is committed to backwards compatibility. I do think once this new API is mature and in core people will stop using XML-RPC because it’s a pain to use.

What Have I Made With It?

  • Josie – A single page web app (and hopefully node.js powered mobile app) framework for use with the REST API.
  • JP-REST-API-Client – A simple client for creating and updating posts via the WordPress REST API via the WordPress HTTP API.
  • Pods JSON API – I added new routes, endpoints and documentation to the add-on to the API for Pods.
  • Pods Deploy – A tool for automating the process of moving Pods configurations between sites.
  • JP-Tax-Query – A custom endpoint for making tax queries via the REST API.
  • JP-REST-Access – A library of WordPress filters for setting cross-origin domain (CORS) headers and improving access to post endpoints.
  • JP-Rest-Cache – A soft-expiring, server-side cache for the REST API.
  • JP-Menu-Routes – Adds routes & endpoints to the REST API.
  • A basic front-end post editor, detailed in this Torque article.