WordPress is getting a JSON Rest API added to core. The first part of the API is actually already included. The endpoint infrastructure is in 4.4. As developers build extensions to the API, we need to take responsibility for our actions and how they can affect a site. WordPress is unique in that it is the ultimate generic API tool and anything can be created utilizing this new tool.
“The infrastructure of the API itself, supports basically anything you can throw at it. If you take away the core endpoints, it is essentially a framework for building APIs, and you can build those however you like.” – Ryan McCue
Namespaces
To avoid collisions, namespaces are something to be thoughtful about. Namespaces are the slugs in the URL before the endpoint. Also, the schema and structure of your data should be a consideration. The core endpoint namespace is:
/wp/
This means it is reserved for core endpoints. Similarly, you may come across plugins that have a namespace. You should probably not add endpoints to a previously used namespace unless the data is specific to that plugin. Think of namespaces like you would with class or function names; they need to be unique. If you are creating endpoints, then add filters in your JSON response code so others can add more data to your existing namespaces endpoints.
What happens when you try and register a namespace and endpoint that already exists? Nothing–it actually gets ignored if the code is loaded after the previous registration. If you register a namespace and a plugin loads before your plugin, then they win and your endpoint will get ignored. To avoid this, create unique namespaces (PLEASE).
If it’s a plugin hosted in the WordPress repo, the slug of the plugin is good namespace for your endpoints. The slug is in the URL after /plugins/. These are unique to each hosted plugin. (This may not be the case for some plugins; they may choose a unique name based on other factors. For example, the core namespace is ‘wp.’)
Options are everything here. You can create wildly different APIs for a myriad of applications. This is one of the reasons I feel WordPress’ Rest API is going to be the go-to framework for creating APIs. You have authentication and administration tools baked in along with Custom Post Types, Taxonomies, and Meta, OH MY! Though, we have almost infinite API possibilities with data structure I think it is good to have some standardized endpoint structures.
Taking core namespaces and endpoints as a basis for creating your own endpoints is the best method. Accessing your custom endpoints will feel natural to a user if they are similar. Looking at the core endpoint for posts:
/wp-json/wp/v1/posts
You may think to create a custom endpoint for a Custom Post Type you might use:
/wp-json/wp/v1/custom-post-type
You could also register your own namespace using the CPT slug:
/wp-json/custom-post-type/v1/posts
The lesson here is you need to decide what is best for your data. If you are adding a simple CPT, you can access the data using the ‘?type=’ parameter when visiting the posts endpoint but if you have complex data structures and a lot of extra meta you may want to go the route of creating unique endpoints. If your plugin will have lots of endpoints, utilizing a custom namespace is the way to go. Note that Custom Post Types will not show unless it has the argument ‘show_in_rest’ during the creation of the type.
JSON Structure
You can hook into the filter ‘rest_prepare_post’. This is the filter you would use to add post meta or any other data to the posts endpoint. Create your own unique filter names, like ‘rest_prepare_my_custom_post_type.’
The filter mentioned above, ‘rest_prepare_post,’ can add or remove anything from a post response. If a plugin filtered the API response and added a new key to the data array, then you came along and added the same key, it would bump their data out of the API response and you may break their site or application. You can add any data in any structured way to the API. This is its greatest power, but it can get wild if there is not some sort of standardized structure. If you have five plugins adding the same meta to five different parent keys it could get messy! Plus, how would a client accessing your API know where the meta for the post is stored?
Conclusion
There is no set method structuring APIs and can’t truly be enforced. Maybe the API needs some guidelines on where to place extra data in the structure. Until then it is best to create our own namespaces / endpoints specific to your data’s needs. If you need to learn how to add the endpoints, hit up the WP-API docs site.
*original image by Nimish Gogri
A few years ago, I used WordPress for a number of small sites, for the church and other non-profits, and it worked very well. I could build the site and then, with a minimum of training, I could turn it over to a layperson to update. It was a great tool.
Now, however, WordPress has reached a level of complexity far, far above what anybody but a highly-trained professional could possibly use. I’m a pretty good coder, and it’s beyond me now.
Pity.
Actually Stephen I would respectfully disagree,
Wordpress is actually extremely simple to use and you don’t have to be a coder to use it! I have interns making websites off of WordPress that have never used WordPress before in a matter of a day or two. What you see these guys writing about here on this site is stuff that is too deep and technical for the average person to understand, but that’s only because the power is there for those that want to get technical, but these days, you can accomplish pretty much everything you need to on WordPress with no programming knowledge whatsoever.
But you are correct, when you read stuff like this, it does look like this stuff is so super technical, as it’s way beyond my scope, but rest assured, WordPress is still as easy to use as it was when it first came out.
Charles
Very true, you can create some extremely custom sites without even touching code just by using plugins and specialty themes. After that you can then do custom coding to fine tune your site functionality.