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?

• Because bike-shedding and internal inconsistency is an enormous cost in terms of wasted developer hours, both in terms of feature developement and ongoing maintenance costs, and the JSON-API spec is good enough and helps prevent both those things.
• The spec is well thought out. It probably has thousands of hours of work put into it, making sure the details are logical and flexible. You won’t get something as good without spending about that same number of hours.
• The documentation is pretty good, with plenty of examples to lead you in the right direction. Don’t waste time with specs that don’t have good examples.
• There is an active community in the Github issue tracker and forum, and they provide a lot of helpful discussion about how to “properly” design an API.

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.

Summary:

• Use the JSON-API spec to prevent the majority of bike-shedding internally to your team.
• Learn it and follow it until you run into a hard limitation (like updating multiple items in one request).
• When that happens, don’t advocate for an official change, just document your change carefully and make it official to your team.
• Let me know if you do! 😄

Related #

• How I use JSON-API.

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