Why JSON:API exists
Ad-hoc REST JSON leads to inconsistent shapes: sometimes { "user": {...} }, sometimes { "data": {...} }, relationship loading via N+1 requests. JSON:API standardizes:
- Resource type and id
- attributes vs relationships
- links (self, related, pagination)
- included compound documents for eager loading
Trade-off: verbosity and learning curve. Wins for multi-client platforms (web + mobile + partners) where consistency reduces SDK maintenance.
Document structure
{
"data": {
"type": "articles",
"id": "1",
"attributes": { "title": "JSON:API" },
"relationships": {
"author": { "data": { "type": "people", "id": "9" } }
},
"links": { "self": "/articles/1" }
},
"included": [
{ "type": "people", "id": "9", "attributes": { "name": "Ada" } }
]
}Single response can carry article + author + comments — client avoids 3 round-trips.
Fetching features
?include=author,comments— compound document?fields[articles]=title,body— sparse fieldsets?page[cursor]=abc&page[size]=20— cursor pagination?filter[status]=published— filtering convention
Errors
JSON:API error objects: status, title, detail, source.pointer (JSON Pointer to field). Multiple errors in one response for validation.
When NOT to use JSON:API
- Internal gRPC mesh — protobuf is enough
- Simple CRUD with one client — OpenAPI + plain JSON is lighter
- GraphQL clients that want arbitrary field selection
Interview answer: "JSON:API is a convention layer on REST — it doesn't replace HTTP semantics from Networking or REST design from Topic 2."
Further Reading
- JSON:API Specification v1.1Reference30m
- JSON:API — Fetching Data (sparse fieldsets, includes, pagination)Reference20m
Hands-On Tasks (Optional)
API design drills and whiteboard exercises — protocol selection, contract design, and bulk-transfer architecture. Assumes Networking and sibling tracks on the hub page (Distributed Systems, Databases, Concurrency, LLD).
- Shape a compound document15m
Model GET /articles/1?include=author,comments with JSON:API `data`, `included`, and `relationships`. Show how it reduces N+1 client round-trips vs naive REST.