HATEOAS JSON:API — Implementing RESTful APIs with the JSON:API Specification

In this tutorial, you will learn about HATEOAS JSON:API. We cover key concepts, practical examples, and best practices to help you master this topic.

JSON:API (application/vnd.api+json) is a full-featured HATEOAS specification that standardizes resource Serialization, relationships, pagination, filtering, sparse fieldsets, and error handling for RESTful APIs.

What You'll Learn

• JSON:API resource objects and identifiers
• Relationships and included resources
• Sparse fieldsets and compound documents
• Pagination, sorting, and filtering conventions
• Error objects and client-server interaction

Why It Matters

JSON:API provides a complete ecosystem with client libraries, server frameworks, and testing tools. DodaTech's reporting API uses JSON:API to serve complex threat analysis reports with related indicators, remediation steps, and audit trails — all in a single request with full hypermedia support.

flowchart TD
    A["JSON:API Document"] --> B["data: Primary resource"]
    A --> C["included: Related resources"]
    A --> D["links: Hypermedia controls"]
    A --> E["meta: Metadata"]
    A --> F["errors: Error objects"]
    B --> G["type + id (required)"]
    B --> H["attributes (data fields)"]
    B --> I["relationships (resource links)"]
    B --> J["links (self, related)"]

What's Next

Compare JSON:API with {{< ilink "HATEOAS" "HATEOAS JSON HAL" }} and {{< ilink "HATEOAS" "HATEOAS Siren" }}, then learn {{< ilink "REST API" "HATEOAS Content Negotiation" }} to serve multiple formats.