The story of JSON:API in Go

Maybe it’s not a very popular format, but I genuinely like it for it’s simplicity and efficiency. The format allows you to express pretty much any underlying resource structure you’d need and puts just enough constraints to keep it simple.

It’s also very efficient in transport since all your duplicate data is addressed in a very nice way.

To read more about the specification itself you’re best visiting jsonapi.org directly. Here I’d like to share experience working with it in Go specifically.

95% of what it should be

I’ve been using JSON:API together with Node.js for a very long time now. And it works perfect there. Mainly thanks to the ultimate flexibility of JavaScript. It gets a little bit more complicated when you introduce TypeScript, but it still remains nice.

However, moving my main backend development to Go I’ve found it to be a little more challenging. You definitely cannot attack it directly and need a solid tooling in place. And to be fair, while the application is simple enough google/jsonapi worked great. But it starts to build up.

Lack of support for complex attributes, inconsistent handling of relationships and a few other things added up enough to reinvent the wheel.

The new library

So here comes the first pass on it. The library can be pulled from MereleDulci/jsonapi and as of now it’s a rather early stage. Very opinionated to make it work with the particular use case I’ve got at hand right now.

It also isn’t optimised at all. Full encode/decode roundtrip is approximately 4-5 times slower than plain encoding/json. Which is quite understandable as encoding/json is used under the hood. But there’s still a rather long way to go to make it more efficient. An iteration on performance is planned after the initial feature set is in place.

For the same reason the API is not stable yet. By the looks of it most of the optimisations are expected to come from metadata caching. But ideally I’d keep the general inputs / outputs contract to stay the same and keep it available.

What’s next?

Most importantly for now - it behaves as an almost drop-in replacement for google/jsonapi. It’s already integrated into one product I build and automated tests are all green with it. It doesn’t appear to have significant performance implications either. Which is a good sign.

Moving on I’m planning to add support for more flexible configuration to make it slightly less opinionated. And write up better documentation for how to us it. As of now the best option is to refer to the tests.