HTTP Link Header

Typ

Der Link-Header ist ein Response-Header, der Beziehungen zwischen Ressourcen definiert (HATEOAS, Pagination, verwandte Ressourcen).

Syntax

Der Header enthält kommaseparierte Link-Relationen mit URI und Relation-Type (rel-Parameter).

http 
Link: </api/products?page=2>; rel="next"
Link: </api/orders/123>; rel="self", </api/users/456>; rel="author"

Direktiven

Der Link-Header verwendet URI-References in spitzen Klammern mit Semikolon-getrennten Parametern, wobei der rel-Parameter die Beziehung definiert.

uri-reference
Die absolute oder relative URI der verknüpften Ressource (in spitzen Klammern).
rel
Der Relation-Type, der die Beziehung zur aktuellen Ressource beschreibt (self, next, prev, first, last, author, etc.).
type
Optionaler Media-Type der verlinkten Ressource (z.B. application/json).
title
Optionale menschenlesbare Beschreibung des Links.

Beispiele

Die folgenden Beispiele zeigen typische Anwendungsfälle für HATEOAS-Navigation, Pagination, API-Discovery und Ressourcen-Relationen.

Pagination mit Link-Header

Ein API-Server verwendet Link-Header für Pagination-Navigation (RFC 8288).

http 
GET /api/v1/products?page=2 HTTP/1.1
Host: api.example.com
Accept: application/json

Response:

http 
HTTP/1.1 200 OK
Content-Type: application/json
Link: </api/v1/products?page=1>; rel="prev",
      </api/v1/products?page=3>; rel="next",
      </api/v1/products?page=1>; rel="first",
      </api/v1/products?page=10>; rel="last"

{
  "items": [
    {"id": "21", "name": "Widget A"},
    {"id": "22", "name": "Widget B"}
  ],
  "page": 2,
  "totalPages": 10
}

HATEOAS mit verwandten Ressourcen

Ein API-Server liefert Links zu verwandten Ressourcen (Author, Comments, etc.).

http 
HTTP/1.1 200 OK
Content-Type: application/json
Link: </api/v1/posts/123>; rel="self",
      </api/v1/users/456>; rel="author"; title="Post Author",
      </api/v1/posts/123/comments>; rel="replies"; type="application/json"

{
  "id": "123",
  "title": "REST API Best Practices",
  "authorId": "456"
}

API-Discovery mit Relation-Types

Ein API-Server nutzt Link-Header für API-Discovery und Service-Vernetzung.

http 
HTTP/1.1 200 OK
Content-Type: application/json
Link: </api/docs>; rel="service-doc"; type="text/html",
      </api/v1/openapi.json>; rel="service-desc"; type="application/openapi+json",
      </api/v1/health>; rel="monitor"

{
  "version": "1.0",
  "status": "operational"
}

HATEOAS-Navigation-Flow

Der Link-Header ermöglicht hypermedia-driven API-Navigation ohne Hard-coded-URLs im Client.

plantuml 
@startuml
!theme plain
skinparam BoxPadding 20
skinparam ParticipantPadding 20

participant "API\nClient" as client
participant "API\nServer" as api

client -> api: GET /api/v1/products?page=1
api --> client: 200 OK\nLink: </api/v1/products?page=2>; rel="next",\n      </api/v1/products?page=1>; rel="first",\n      </api/v1/products?page=10>; rel="last"\n[Products Page 1]

client -> client: Parse Link-Header\nExtract rel="next"

client -> api: GET /api/v1/products?page=2\n(from Link-Header)
api --> client: 200 OK\nLink: </api/v1/products?page=1>; rel="prev",\n      </api/v1/products?page=3>; rel="next",\n      </api/v1/products?page=10>; rel="last"\n[Products Page 2]

client -> client: Parse Link-Header\nExtract rel="next"

client -> api: GET /api/v1/products?page=3\n(from Link-Header)
api --> client: 200 OK\nLink: </api/v1/products?page=2>; rel="prev",\n      </api/v1/products?page=4>; rel="next",\n      </api/v1/products?page=10>; rel="last"\n[Products Page 3]

note over client: Client navigiert\ndurch Pagination\nOHNE URL-Konstruktion

client -> api: GET /api/v1/products?page=10\n(rel="last" from Link-Header)
api --> client: 200 OK\nLink: </api/v1/products?page=9>; rel="prev",\n      </api/v1/products?page=1>; rel="first"\n[Products Page 10 - Last]

note over client: HATEOAS-Prinzip:\nServer kontrolliert\nNavigation-URLs
@enduml

Vorteile für die Systemarchitektur

  • HATEOAS-Implementierung für self-documenting REST-APIs
  • Standardisierte Pagination ohne Custom-Response-Body-Felder
  • API-Discovery via Service-Relation-Types (RFC 8288)
  • Client-Entkopplung durch Server-controlled Navigation
  • Kombinierbar mit HAL, JSON:API und andere Hypermedia-Formate

Spezifikation

RFC 8288 (Web Linking) definiert den Link-Header als standardisiertes Format für Ressourcen-Beziehungen in HTTP-APIs und Hypermedia-Systemen.

Weitere Spezifikationen

Location Header, Referer Header