JSON-API: Convention over Configuration with Standardization

One of the most difficult things a developer faces is choice- which language, framework, method etc. and when to use something or when not to use something.  The stress for most developers is palpable, and the choices are a crippling part of this anxiety.  Enter ‘convention over configuration’.

At its core, the concept of applying convention over configuration is about reducing the total number of choices a developer has to make.  For example, Ruby on Rails has strict naming conventions from the view layer all the way through to the database layer.  Every name is expected to follow these conventions.

But what about APIs?

APIs are tricky.  Creating them is tricky, consuming them is tricky.  Sometimes the people who create them aren’t wearing the shoes of the people consuming them.  Sometimes two different people develop two different end points in the same API and the data returned by the two responses aren’t traversable in the same way.

This is a core problem caused by a developer’s choice- especially with multiple cooks in the kitchen, there’s no guarantee what you have today will look anything like what you get tomorrow.  The solution many framework developers take is to apply convention over configuration to their platforms, so why shouldn’t we do the same with our public or third-party facing APIs?  Why should we expect developers to constantly be micro-managing their API consumers down to the detail?

Standardization drives simplicity: API consumers should be able to understand what they are receiving from the endpoint without any hassle and it should all look the same, even if the data is different.  This is standardization.  Every response takes the same form, every consumer has similar or near identical code for traversing an API.  What it becomes is an implementation detail rather than a core part of your architecture.

The JSON-API Standard

So how does it look in the wild?  You can head over to to review the standard and its core best practices.  If you want to get started and you’re a Rails developer, wander over to GitHub and checkout this Gem:

By following the JR documentation, you can turn your Rails API into a JSON-API compliant interface for your consumers. You should dogfood your changes and create an Ember app to the see just how easy it is to consume your new APIs by using the JSONAPIAdapter (  Pagination and relationship traversal has never been so easy-breezy-beautiful.

The take away from all of this is that standardization simplifies the process of consuming your API to the point of making it a trivial implementation detail rather than a chore or an architectural decision.  We must put ourselves in the shoes of our clients and understand that the API endpoints they access are a detail and not the backbone of their applications. We must remember to be kind to our clients in the hopes they will reciprocate by supporting our products lovingly.