application/hal+json

API Design

Meaning

A media type identifier for HAL-formatted JSON responses in REST APIs. It signals to clients that the response body follows the HAL specification, embedding hypermedia `_links` for navigation between related resources. Developers reach for it when designing or consuming hypermedia-driven APIs that need discoverable link relations.

Primary Function

API media type specification

Communicative Purpose

Enables hypermedia-driven REST APIs by declaring a standardized format that embeds navigational links alongside resource data.

Pattern

Content-Type: application/hal+json header on responses containing HAL-formatted JSON bodies

Função primária

API media type specification

Propósito comunicativo

Enables hypermedia-driven REST APIs by declaring a standardized format that embeds navigational links alongside resource data.

Situações de gatilho

REST API design: returning resources with discoverable hypermedia links

Contextos

REST APIs, HATEOAS architectures, Spring HATEOAS, hypermedia-driven client libraries

Padrão

Content-Type: application/hal+json header on responses containing HAL-formatted JSON bodies

Colocados típicos

Content-Type header
Accept header
_links
_embedded
self link
link relations
HATEOAS

Substituições comuns

application/json — no embedded hypermedia links
loses discoverability

Erros comuns

Treating HAL+JSON as plain JSON — ignores _links and _embedded, breaks hypermedia navigation

Similar / contraste

application/json — plain JSON without hypermedia constraints

Interferências

Coming from plain JSON APIs: may ignore _links and _embedded fields — HAL+JSON requires parsing these for navigation

Família do chunk

application/json
application/vnd.api+json
application/ld+json
HATEOAS
link relations

Nuance

When NOT to use: simple CRUD APIs without hypermedia needs add unnecessary parsing overhead

Efeito pragmático

Enables self-describing REST APIs where clients can navigate resources via standardized link relations without hardcoded URLs.

Dica de memória

application/hal+json is the MIME type that tells clients 'expect JSON with a _links map for navigation' — like a treasure map where every resource points to its neighbors.

Upgrade path

HATEOAS-compliant API design with link relations and content negotiation

Frequência: LowFormulaicidade: FixedPrioridade de aquisição: Passive recognitionPrioridade de output: InputTag de espaçamento: Long-term

Examples

import requests response = requests.get( "https://api.example.com/articles/42", headers={"Accept": "application/hal+json"} ) article = response.json() author_url = article["_links"]["author"]["href"] author = requests.get(f"https://api.example.com{author_url}").json()

from flask import Flask, jsonify app = Flask(__name__) @app.route("/articles/<int:article_id>", methods=["GET"]) def get_article(article_id): article = {"id": article_id, "title": "REST API Design", "author": "Jane"} links = { "self": {"href": f"/articles/{article_id}"}, "author": {"href": "/authors/jane"}, "comments": {"href": f"/articles/{article_id}/comments"} } response = jsonify({**article, "_links": links}) response.headers["Content-Type"] = "application/hal+json" return response

def follow_link(document, relation): return document["_links"][relation]["href"] article = { "id": 42, "title": "REST API Design", "_links": { "self": {"href": "/articles/42"}, "comments": {"href": "/articles/42/comments"} } } self_url = follow_link(article, "self") comments_url = follow_link(article, "comments")