I have been writing about AngularJS and the WP-API for over a year now, and in that year the WP-API has flourished into an awesome feature plugin slated for core integration. When? No one really knows yet, but speculation is on it happening in 2015, which means one of the next 2 big releases (probably the latter of the two). As it has grown, more people are talking about it, and using it to do amazing things. From my modest CodeCavalry.com to some of the more unique and awesome uses like AppPresser which allows you to build iOS and Android apps from your WordPress site. However there is a lot of power you may not know about the WP-API, things you can do with it that are awesome to build new awesome things.

What is extending? When should you extend the WP-API?

Extending the WP-API can be done easily and there are many use cases for when it is needed. When I talk about extending I usually refer to adding in new custom routes and endpoints.

A route is something like /posts which by default on an WordPress install with WP-API would return you a JSON object of all the posts in your site. Since it runs just like WP_Query, there are many filters and additions you can add, for example if you have a custom post type, /posts?type=CPT_SLUG this would return a JSON object of just the CPT that you requested. There are many more filters that you can add in through the filter array, like /posts?filter[author]=author_id (note: user_nicename would also work) would return a JSON object of all the posts created by that author.

An endpoint is the function that is called when a specific route is hit, and endpoints are sorted by their CRUD HTTP Request (POST/UPDATE/DELETE). So you can have 1 route with multiple endpoints based on the request type.

I just want to add some data to the JSON response, should I create a new route?

No, that is the great thing about the team behind WP-API, they are thinking about these use cases and creating awesome filters that you can use to tap into the data, so you don’t have to create a custom route and endpoint. This means that you don’t have to deal with authorization, validation, etc. that the WP-API already handles. You can use the json_prepare_post filter to alter the data that WP-API returns.

For example if you wanted to add in all the post meta data.

With this filter you can add any data you may want to each individual post as it is returned, so you have that data when you call /posts or /posts/post_id to get a single specific post data.

I have a custom data structure and need to mix data from other sources

This would be a good use case for extending out the API. In CodeCavalry’s code, I had to extend the typical /post route because I needed to add in custom meta data to the post and interact with other API’s including Stripe, and Firebase.

Extending the API is easy, here is an example of adding in a new route and the endpoint function – in this case I am just going to take the data that you send the route in the request, and send it back so it returns as a JSON object.

Filters might help do the trick

There are many filters available so check the docs on WP-API.org for filters and other ways to extend or manipulate the data without creating a route and endpoint.

Authentication for your WP-API endpoint is easy, and should be done

AppPresser wrote an article for how to authenticate easily for any route. It is important to add authentication when you are adding in a new endpoint, for example in CodeCavalry we used the currently logged in user a lot to verify certain routes. It is also how we can easily add an author or user to some data, or more importantly, if no one is logged in then it should return a WP_Error.

For authentication, it is just like above a filter! I’m beginning to think the motto for this should just be “There is a filter for that”.

With authentication, that filter is json_authentication_errors, and it is pretty easy to use too!

Note: above example copied from AppPresser’s article

Extending WP-API is good, but keep others in mind

Extending the API is awesome, whether you are adding in a new route or just adding in some data. You can also remove data, and that is where things can get tricky. When are you are altering a default WP-API endpoint’s response, you have to keep in mind other applications, plugins, etc. that may need that data. For example, if you wanted to remove a piece of the POST object since your plugin doesn’t need it, don’t think that your plugin or app is the only one (unless you have 100% control) that needs that POST data.

I think there is a good example in jQuery. Many plugins used to (and still do) enqueue their own jQuery version for whatever reason, and de_enqueue the default jQuery. This is problematic with other plugins or themes that may need the jQuery that is built into WordPress. There are many other examples, like PHP namespacing, etc. however I see as how WP-API comes into core this being a problem, especially with those users and implementors who install 10+ plugins to get the functionality they need out of a site.

What are you building? Did I miss anything?

What are you best practices or standards when building with WP-API? Are you conscious of the other plugins that will need to use it?

I’d love to add to this article, so comment or message me and I will add new best practices that you think are important for people just starting out with the WP-API.

There are 11 comments Join the conversation

Comments are closed.