HTTP-Location-Header

Typ

Der Location-Header ist ein Response-Header, der die URI einer Ressource angibt (Redirect-Ziel oder neu erstellte Ressource).

Syntax

Der Header enthält eine absolute oder relative URI zur Ziel-Ressource.

http 
Location: https://api.example.com/orders/12345
Location: /api/v1/products/98765

Direktiven

Der Location-Header akzeptiert eine URI-Reference (absolute oder relative URI) ohne zusätzliche Parameter.

absolute-uri
Eine vollständige URI mit Schema, Host und Pfad (empfohlen für Redirects).
relative-uri
Eine Pfad-basierte URI relativ zum Request-URI (zulässig bei 201 Created).

Beispiele

Die folgenden Beispiele zeigen typische Anwendungsfälle für Resource-Creation (201 Created), Redirects (3xx) und RESTful-Patterns.

Resource-Creation mit 201 Created

Ein API-Server erstellt eine Ressource und gibt die URI der neuen Ressource im Location-Header zurück.

http 
POST /api/v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "productId": "prod_789",
  "quantity": 2,
  "customerId": "cust_456"
}

Response:

http 
HTTP/1.1 201 Created
Location: https://api.example.com/api/v1/orders/12345
Content-Type: application/json
ETag: "a7f3b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9"

{
  "id": "12345",
  "status": "created",
  "productId": "prod_789",
  "quantity": 2,
  "createdAt": "2025-10-01T10:30:00Z"
}

Redirect mit 302 Found

Ein API-Server leitet eine Anfrage an eine neue URI weiter (temporärer Redirect).

http 
GET /api/v1/products/legacy-sku-42 HTTP/1.1
Host: api.example.com
Accept: application/json

Response:

http 
HTTP/1.1 302 Found
Location: https://api.example.com/api/v2/products/sku-42-updated
Content-Type: application/json

{
  "message": "Product moved to new API version",
  "newLocation": "/api/v2/products/sku-42-updated"
}

Permanent Redirect mit 301 Moved Permanently

Ein API-Endpunkt wurde dauerhaft verschoben und leitet Clients zur neuen URI.

http 
GET /api/v1/legacy-endpoint HTTP/1.1
Host: api.example.com

Response:

http 
HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/api/v2/new-endpoint
Cache-Control: max-age=31536000

Resource-Creation-Flow

Der Location-Header ermöglicht RESTful-Ressourcen-Erstellung mit expliziter URI-Rückgabe für nachfolgende Operationen.

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

participant "API\nClient" as client
participant "API\nServer" as api
database "Database" as db

client -> api: POST /api/v1/orders\nContent-Type: application/json\n{\n  "productId": "prod_789",\n  "quantity": 2\n}

api -> db: INSERT INTO orders\n(product_id, quantity, status)\nVALUES ('prod_789', 2, 'pending')\nRETURNING id

db --> api: Order created\nid: 12345

api -> api: Generate Location URI:\nhttps://api.example.com/api/v1/orders/12345

api --> client: 201 Created\nLocation: https://api.example.com/api/v1/orders/12345\nETag: "abc123"\n{\n  "id": "12345",\n  "status": "created"\n}

note over client: Client speichert\nLocation-URI für\nnachfolgende Operationen

client -> api: GET /api/v1/orders/12345\n(from Location-Header)

api -> db: SELECT * FROM orders\nWHERE id = 12345

db --> api: Order Data

api --> client: 200 OK\n{\n  "id": "12345",\n  "status": "pending",\n  "productId": "prod_789"\n}

client -> api: PATCH /api/v1/orders/12345\n(from Location-Header)\n{\n  "status": "confirmed"\n}

api -> db: UPDATE orders\nSET status = 'confirmed'\nWHERE id = 12345

db --> api: 1 row updated

api --> client: 200 OK\n{\n  "id": "12345",\n  "status": "confirmed"\n}

note over client: RESTful-Pattern:\nLocation-Header\nentkoppelt Client von\nURI-Konstruktion
@enduml

Vorteile für die Systemarchitektur

  • RESTful-Resource-Creation mit expliziter URI-Rückgabe
  • Client-Entkopplung durch Server-controlled URIs
  • Redirect-Unterstützung für API-Versioning und Legacy-Migration
  • Kombinierbar mit 201 Created für POST-Responses
  • Standard-Unterstützung in HTTP-Clients für automatische Redirect-Verfolgung

Spezifikation

RFC 9110 (HTTP Semantics) definiert den Location-Header als Response-Header für Redirect-Ziele und neu erstellte Ressourcen-URIs.

Weitere Spezifikationen

HTTP Status 201 - Created, HTTP Status 301 - Moved Permanently, HTTP Status 302 - Found