JSON:API is the specification that tried to solve one of the most tedious and most real problems in API design: the endless bikeshedding over how to structure a JSON response. Every team that builds a JSON API has the same arguments — how do you represent a resource, how do you include related resources, how do you handle pagination, filtering, sorting, errors, where does the metadata go. These arguments are mostly unproductive, because there’s no single right answer, just a lot of reasonable conventions, and every team reinvents them from scratch. JSON:API, which emerged from the work of Steve Klabnik and others around 2013, said: let’s just agree on a convention, write it down, and stop arguing. It’s a specification for building APIs in JSON that standardizes resource representation, relationships, includes, pagination, and errors — so teams can adopt a proven convention instead of bikeshedding their own.
The anti-bikeshedding value is the thing I’d emphasize most, because it’s JSON:API’s real contribution. Steve Klabnik, whom I got to know through the hypermedia community and the API Craft gatherings in Detroit, framed JSON:API as convention-driven API design — and the word “convention” is the key. The value isn’t that JSON:API’s specific choices are uniquely correct; it’s that they’re shared. When a team adopts JSON:API, they inherit a complete, thought-through set of answers to all the structural questions, and they can spend their design energy on what actually matters — the resources and capabilities of their API — instead of relitigating how to format a response. This is the same value proposition as any good convention: it removes a class of decisions from the table so you can focus on the decisions that matter. JSON:API is, at its heart, a productivity and consistency tool disguised as a media type.
JSON:API occupies an interesting place between simple REST and full hypermedia, which is part of what makes it pragmatic. When I cataloged the hypermedia media types with the leaders of that community — HAL, Siren, Collection+JSON, JSON-LD, UBER, Mason, and JSON:API — JSON:API was one of the more adopted ones precisely because it struck a usable balance. It includes hypermedia concepts: it has a structured way to represent relationships between resources and to include related resources in a response, which is genuinely hypermedia-flavored. But it doesn’t demand the full HATEOAS commitment that scared most developers away from pure hypermedia. JSON:API gives you relationship handling, included resources, and a consistent structure without requiring you to rebuild your client around following links. That pragmatic middle position — more structured than ad-hoc JSON, less demanding than full hypermedia — is why JSON:API found real adoption where stricter hypermedia formats didn’t.
The relationship-handling is JSON:API’s most distinctive technical feature, and it addresses a real pain point. One of the genuinely hard problems in REST API design is dealing with related resources: when you fetch an article, do you also get the author, the comments, the tags? Fetch them separately and you have the N+1 problem; embed them all and you over-fetch. JSON:API’s approach — with its compound documents, its “included” section, and its sparse fieldsets — gives a standardized way to let the consumer ask for related resources in a controlled way. This is solving the same over-fetching and under-fetching problem that GraphQL addresses, but within a RESTful, convention-based framework rather than a query-language one. The relationship handling is where JSON:API does real work, and it’s why teams with genuinely interconnected resources found it valuable.
JSON:API’s place in the modern specification ecosystem is as one option among the loose federation of API standards, and I’ve framed it that way consistently. In my analysis of the loose federation of API standards, JSON:API sits alongside OpenAPI, AsyncAPI, JSON Schema, and GraphQL as part of the broader landscape of specifications that the API world has produced. It’s not a universal winner the way OpenAPI became for API description, but it’s a durable, useful standard for the specific job it does — structuring JSON API responses consistently. The 2024 work on building an OpenAPI and JSON Schema for JSON:API reflects that it remains relevant enough to warrant integration with the dominant description and validation standards. JSON:API and OpenAPI aren’t competitors; OpenAPI describes the API, and JSON:API can be the convention the API’s responses follow.
The honest assessment, which I’d apply to JSON:API as to all the hypermedia and structural standards, is that its adoption was real but bounded, and that’s fine. JSON:API never became the universal way to build JSON APIs — most APIs still use ad-hoc JSON structures, making the same decisions JSON:API tried to standardize, because the gravitational pull toward “just structure it however makes sense to us” is strong. But JSON:API found a genuine constituency among teams who valued the convention, who had complex resource relationships to manage, and who wanted to stop bikeshedding. It’s a good example of a standard that solved a real problem well without conquering the world — which is the fate of most standards, and not a failure. JSON:API earned a durable place as one of the considered, well-designed options a team can reach for when they want a proven convention for structuring their JSON API rather than inventing their own. In a field that loves to reinvent the same wheels, a standard that lets you stop reinventing one particular wheel is a genuine contribution, even if not everyone adopts it.
References
- Quora Exposes JSON API
- What Is A Hypermedia API
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- My Discussion Today With 6 Hypermedia Leaders At API Craft In Detroit
- API Is Not Just REST
- REST And Hypermedia And GraphQL And gRPC And Event-Driven
- A Loose Federation Of API Standards
- An OpenAPI And JSON Schema For JSON:API
