HTTP Prefer Header

Der HTTP-Header Prefer ist ein Request-Header, der optionale Präferenzen des Clients für die Verarbeitung des Requests und die Antwort-Formatierung an den Server kommuniziert. Server können diese Präferenzen respektieren, sind aber nicht dazu verpflichtet.

Typ

Request-Header

Syntax

Der Header listet eine oder mehrere Präferenzen mit optionalen Parametern auf.

http 
Prefer: respond-async
Prefer: return=representation
Prefer: wait=10

Direktiven

Die Direktiven definieren Client-Präferenzen für Verarbeitungslogik und Antwortformatierung.

respond-async
Client bevorzugt asynchrone Verarbeitung für lange Operationen mit sofortiger 202 Accepted Antwort.
return=minimal
Client möchte minimale Antwort ohne Body (nur Status und Location Header).
return=representation
Client möchte die vollständige Ressourcen-Repräsentation in der Antwort (Standard bei POST/PUT).
wait=<seconds>
Maximale Zeit in Sekunden, die der Client auf synchrone Verarbeitung warten möchte, bevor auf async umgeschaltet wird.

Beispiele

Nachfolgend finden Sie praktische Anwendungsbeispiele für den Prefer-Header.

Beispiel 1 Asynchrone Verarbeitung für lange API-Operationen

http 
POST /api/reports/generate HTTP/1.1
Host: api.example.com
Content-Type: application/json
Prefer: respond-async

{"report_type": "annual", "year": 2024}

Server akzeptiert sofort und verarbeitet Report asynchron, Antwort enthält Location für Statusabfrage.

http 
HTTP/1.1 202 Accepted
Location: /api/reports/tasks/abc-123
Preference-Applied: respond-async

Beispiel 2 Minimale Antwort bei POST-Operationen

http 
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Prefer: return=minimal

{"name": "Max Müller", "email": "max@example.com"}

Server erstellt Benutzer und gibt nur Status 201 mit Location Header zurück, kein Response-Body.

http 
HTTP/1.1 201 Created
Location: /api/users/78901
Preference-Applied: return=minimal

Beispiel 3 Vollständige Repräsentation nach PATCH

http 
PATCH /api/orders/12345 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Prefer: return=representation

{"status": "shipped"}

Server wendet Änderung an und gibt vollständiges Order-Objekt in Antwort zurück.

http 
HTTP/1.1 200 OK
Content-Type: application/json
Preference-Applied: return=representation

{"id": 12345, "status": "shipped", "updated_at": "2024-03-15T14:30:00Z"}

Async Processing Flow

Asynchrone API-Verarbeitung mit Prefer Header

Vorteile für die Systemarchitektur

Präferenz-basierte API-Kommunikation verbessert Flexibilität und Performanz.

  • Optimierte Bandbreite: Clients können minimale Antworten anfordern, wenn sie keine Payload-Daten benötigen
  • Asynchrone Skalierung: Lange Operationen blockieren keine HTTP-Verbindungen und verbessern Server-Durchsatz
  • Flexible Timeouts: Clients können eigene Wartezeitgrenzen definieren statt auf fixe Server-Timeouts angewiesen zu sein

Spezifikation

RFC 7240 – Prefer Header for HTTP https://www.rfc-editor.org/rfc/rfc7240.html

Weitere Spezifikationen

Preference-Applied Header, HTTP Status 200 - OK