JSON:API is a specification for building APIs in JSON that standardizes how clients fetch and modify resources, including pagination, filtering, sparse fieldsets, and relationships. It reduces bikeshedding by defining conventions for request and response document structure.
JSON:API
JSON:API is a specification for building APIs in JSON. It standardizes the shape of request and response documents — how resources are represented, how they are fetched and modified, and how pagination, filtering, sparse fieldsets, and relationships are expressed. Its stated goal is to end the endless per-team debates over payload conventions by giving everyone a shared, well-documented default.
- A resource document format - Every response follows a consistent structure with
data,type,id,attributes, andrelationships. - Relationships and compound documents - Related resources can be linked and side-loaded with
includedto avoid extra round trips. - Built-in query conventions - Pagination, sorting, filtering, and sparse fieldsets have defined query-parameter patterns.
- Hypermedia links - Standard
linksmembers make responses self-describing and navigable.
In API operations, JSON:API is a way to adopt a proven set of conventions instead of reinventing them for every service — and, importantly, it now travels with machine-readable descriptions. As I have written, there is an OpenAPI and JSON Schema treatment of JSON:API, which means a team can describe, validate, and govern a JSON:API surface with the same tooling they use everywhere else. That combination of a strong response convention plus a formal contract is exactly what makes an API predictable enough for both integrators and agents to consume with confidence.
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
A OpenAPI and JSON Schema for JSON:API
2024-10-10
Quora Exposes JSON API
2011-01-08
