WP-API: Endpoint Namespaces

WP-API: Endpoint Namespaces

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

Leave a Reply

Your email address will not be published. Required fields are marked *

Bitnami