Tobias Davis

Designing better software systems.

Free resources for building better systems, get on the email list, or use RSS.

Site logo image

Don't bikeshed the JSON API specs

I’ve used the JSON-API spec for a while now, and in the last few months I’ve been in a number of best-practice API design discussions and wanted to share some things that have been brought up, and that I’ve thought about since starting to use the spec everywhere.

The first thing you should know is that I don’t think the JSON-API spec is perfect. I even wrote an article about how I use it differently, and I’m not 100% convinced that there’s not a truly better solution out there.

Why would I advocate for something that’s not perfect?

All these things add up to a solid business choice as a foundation for your API design.

The most important thing I can tell you about using the spec is that it is likely that at some point you will find a limitation in it that you need to overcome. For me it was the fact that the spec doesn’t let you PATCH multiple resources at once. This was a fixed business requirement.

Your initial desire may be to get involved in a Github discussion, attempting to push the spec in a particular direction that you (and other smart people!) think makes sense.

This is foolishness.

The truth is that the JSON-API spec is designed to be a very solid anti-bikeshedding document. But as it gains in popularity, it becomes the world’s biggest bike shed, and everyone wants to paint it their color.

Don’t waste your time trying to convince the masses that a green bike shed would be better than a orange one.

What should you do?

First, spend a good amount of time looking through the issue tracker and forum to see what other people say. Try to find different solutions that make sense with your business needs, and that “feel” intuitive to the original spec.

Second, take those things you found, and write your own addendum/modification to the original spec. If you have other developers on your team, talk this document over with them and get some buyoff. (If you don’t have other developers available, you can go to the JSON-API forums, or even contact me if you want!)

Finally, put this document somewhere where your team has access to it. Maybe commit it to your code repository if all your API code is in the same place. Something to make it official as a design spec. Ideally, post it as a public document somewhere, like I did when I wrote about how I use collections a little differently.

Then you just say, to yourself and your team:

We follow the JSON-API spec with $CHANGES.

Don’t get into bikeshedding the world’s biggest bike shed–don’t try to change the spec itself.


Banner image found on WikiMedia. Original and modified image are available under the Creative Commons Attribution-Share Alike 4.0 International license.

Need guidance on API design and best practices? Send me a message, I’d love to help make your project a success!

Your thoughts and feedback are always welcome! 🙇‍♂️