HATEOAS Media Types — Understanding Hypermedia Media Types: HAL, JSON:API, Siren, and More

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

HATEOAS media types define how links, actions, and embedded resources are structured in HTTP responses, with each format (HAL, JSON:API, Siren, Collection+JSON) offering different trade-offs for discoverability and client ergonomics.

What You'll Learn

• HAL (application/hal+json) structure and conventions
• JSON:API (application/vnd.api+json) resource model
• Siren (application/vnd.siren+json) actions and fields
• Collection+JSON for collection-oriented APIs
• Choosing the right media type for your API

Why It Matters

The media type determines how clients navigate your API. Choosing the wrong format makes client development harder and limits discoverability. DodaTech's public threat API uses Siren for rich action definitions, while internal services use HAL for simplicity.

flowchart TD
    A["Choosing a HATEOAS Media Type"] --> B{"Need rich actions
with form fields?"}
    B -->|"Yes"| C["Siren"]
    B -->|"No"| D{"Need JSON:API
ecosystem tools?"}
    D -->|"Yes"| E["JSON:API"]
    D -->|"No"| F{"Focus on simple
resource navigation?"}
    F -->|"Yes"| G["HAL"]
    F -->|"No"| H["Collection+JSON
or Custom"]

What's Next

Compare these formats in {{< ilink "HATEOAS" "HATEOAS Link Formats" }} with practical examples, then see {{< ilink "REST API" "HATEOAS Content Negotiation" }} for serving multiple formats.