API specification

Standardizes how JSON resources, relationships, and compound documents are exchanged over HTTP, reducing ad-hoc API design decisions.

REST API design: defining resource representations and relationship links between entities; API consumption: parsing standardized JSON responses with included related resources; API documentation: generating client SDKs from a machine-readable schema

REST APIs, web services, client-server architectures, API design, OpenAPI ecosystem

define resource types → specify attributes and relationships → serialize with JSON:API document structure (data, included, links, meta)

• REST
• HTTP
• JSON
• OpenAPI
• resource
• relationship
• compound document
• sparse fieldsets
• pagination links

• Plain JSON REST: no standardized shape
• each API invents its own conventions
• GraphQL: single endpoint with query language instead of resource-oriented URLs
• HAL: older hypermedia standard with similar goals but less adoption

Treating JSON:API as just a JSON format: ignores the specification's rules for document structure, links, and relationships; ignoring the 'included' section: fetches related resources with N+1 requests instead of using compound documents; mixing JSON:API and non-JSON:API endpoints in the same API: breaks client expectations and tooling; omitting 'type' field on resources: the 'type' is required to identify the resource class; confusing attributes with relationships: relationships must be objects with links, not flat IDs

GraphQL: query-driven, single endpoint vs. resource-oriented URLs; REST: general architectural style vs. specific JSON serialization rules; HAL: hypermedia links with different conventions; OData: Microsoft's query-based API standard

Coming from plain REST: may assume any JSON shape is valid JSON:API — JSON:API mandates specific top-level keys (data, errors, meta) and resource object structure; Coming from GraphQL: may try to embed queries in the request body — JSON:API uses URL query parameters for sparse fieldsets, includes, and sorting

• REST
• GraphQL
• HAL
• OData
• OpenAPI specification

When NOT to use: simple CRUD apps with one resource type where the overhead of compound documents and relationship objects adds complexity without benefit; Performance: compound documents can produce large payloads when eager-loading many relationships — use sparse fieldsets to limit attributes; Boundary conditions: JSON:API requires a 'type' on every resource object, and relationship objects must contain at least one of links, data, or meta

Enables consistent client-server contracts, reduces API documentation burden, and allows generic tooling (serializers, client generators) to work across any JSON:API-compliant service.

JSON:API is like a postal service with rigid envelope rules — every package (resource) must have a return address (type), a label (id), and a contents list (attributes), with optional attached parcels (relationships) bundled in the same delivery.

JSON:API extensions (profile negotiation, cursor-based pagination) or transitioning to GraphQL for query-heavy APIs