Is JSON API suitable for use in public APIs?

JSON API seems like a great solution for building application frontends that need to communicate with their backend, and we’re in fact moving in this direction. Most agree this is a very good thing, but we’ve been debating the idea of switching our public API (used by third parties to integrate with our system) to using it as well. One concern is that since these third parties aren’t actually building apps on our API (their apps have their own internal API presumably) many of the sophisticated features of JSON API will actually just get in the way of folks trying to integrate us into their systems. Usually this involves copying data to/from the third party’s model to ours. For these types of consumers, an argument can be made that a simple JSON structure (even with more nesting) may actually be easier/better to consume.

Also, if anyone knows of any mainstream APIs using JSON API, I’d love see how they handle this.

I’d love to hear some different opinions on this, thanks!

1 Like

an argument can be made that a simple JSON structure (even with more nesting) may actually be easier/better to consume.

Certainly. An API should first and foremost be useful to its consumers; that’s why you are creating it, after all. But don’t underestimate the power of a rich JSON:API-compliant API. The way it centers on resources, the ability to trim the response using sparse fieldsets, and particularly the ability to include related resources may be very useful. You may, of course, implement all of that in your own non-JSON:API format, but then you’re on your own when it comes to specifying/documenting it, and there will be no ready-made libraries for your clients to use. JSON:API on the other hand has a rich ecosystem of client (and server) implementations for many languages.

My company is currently using JSON:API for one such public “move data from us to them” API. Clients sometimes need to be told explicitly that yes, you can actually include related resources (they don’t read the spec that thoroughly…), but when they discover that, I think they find that they can get most of the data they need in a single request. Due to how flexible it is, as long as you design the resources properly, it is also very low maintenance for us. We don’t have to add new endpoints for every client’s wishes since the API already supports what they want.

We are also creating an ecosystem of JSON:API-compliant APIs for an entirely new product, and I think the intention is to open up those APIs in a similar way later on.

4 Likes