Prefer header
Der HTTP-Prefer
-Header ermöglicht es Clients, Präferenzen für bestimmte Serververhaltensweisen während der Anfragenverarbeitung anzugeben.
Hinweis:
Browser behandeln die Prefer
- und die Preference-Applied
-Header nicht: Sie werden in benutzerdefinierten, implementierungsspezifischen Clients verwendet.
Stellen Sie sicher, dass sowohl der Client als auch der Server diesen Header unterstützen, bevor Sie sich im Produktionsbetrieb darauf verlassen.
Server sollten stillschweigend Präferenzen ignorieren, die sie nicht unterstützen, als ob der Header nicht vorhanden wäre.
Header-Typ | Anforderungsheader |
---|---|
Verbotener Header-Name | Nein |
Syntax
Prefer: <preference>
Direktiven
respond-async
-
Der Client bevorzugt asynchrone Verarbeitung. Beispielsweise könnte der Server mit einer
202 Accepted
-Antwort, die besagt, dass die Anfrage angenommen wurde, antworten, zusammen mit demLocation
-Header, der eine URL enthält, die der Client verwenden kann, um den Status der Verarbeitung zu überwachen. return=minimal
-
Fordert, dass der Server minimalen Inhalt zurückgibt (eine nur aus Headern bestehende Antwort).
return=representation
-
Fordert eine vollständige Repräsentation der Ressource in der Antwort an.
wait=<seconds>
-
Die Zeit, innerhalb der der Client erwartet, dass der Server eine Antwort liefert, ab dem Punkt, an dem die Anfrage empfangen wurde. Wenn die
respond-async
-Präferenz ebenfalls angegeben ist, sollte der Server asynchron antworten, wenn die Verarbeitung der Anfrage die Wartezeit überschreiten wird. Andernfalls sollte der Server davon ausgehen, dass der Client nach derwait
-Zeit ein Timeout erwartet (das Antwortverhalten hängt von der Implementierung des Servers ab). handling=lenient
-
Der Client wünscht, dass der Server eine nachsichtige Validierung und Fehlerbehandlung bei der Verarbeitung der Anfrage anwendet.
handling=strict
-
Der Client wünscht, dass der Server eine strikte Validierung und Fehlerbehandlung bei der Verarbeitung der Anfrage anwendet.
- Benutzerdefinierte Präferenz
-
Anbieter oder Anwendungen können ihre eigenen Präferenzen definieren, um spezifische Bedürfnisse zu erfüllen. Beispiel:
Prefer: timezone=America/Los_Angeles
.
Beispiele
Minimalantwort anfordern
Die folgende Anfrage fordert eine minimale Antwort an.
Dies ist typischerweise eine Antwort, die nur aus Headern besteht (im Gegensatz zu return=representation
, bei der eine Repräsentation im Antwortkörper enthalten ist):
POST /resource HTTP/1.1
Host: example.com
Content-Type: application/json
Prefer: return=minimal
{"id":123, "name": "abc"}
Der Server antwortet mit einem 201
, enthält jedoch keinen Antwortkörper.
Der Location
-Header enthält eine URL zum Standort der neu erstellten Ressource.
Es ist nicht notwendig, einen Preference-Applied
-Header einzuschließen, da das Fehlen eines Antwortkörpers einfach erkennbar ist:
HTTP/1.1 201 Created
Location: /resource?id=123
Asynchrone Verarbeitung anfordern
Dieses Beispiel verlangt, dass der Server eine asynchrone Verarbeitung startet:
POST /process HTTP/1.1
Host: example.com
Prefer: respond-async
{
"task": "check-broken-links"
}
Der Server antwortet mit einer 202 Accepted
-Antwort, die besagt, dass die Anfrage angenommen wurde und noch nicht asynchron abgeschlossen ist.
Ein Location
-Header verweist auf einen Statusmonitor, der den Status der Verarbeitung darstellt:
HTTP/1.1 202 Accepted
Location: http://example.com/tasks/123/status
Mehrere Präferenzen angeben
Die folgende Anfrage enthält zwei Präferenzen; timezone=Jupiter/Red_Spot
, die eine Zeitzonenpräferenz für den Client angibt, und handling=strict
für strikte Validierung:
GET /events HTTP/1.1
Host: example.com
Prefer: handling=strict, timezone=Jupiter/Red_Spot
In dieser Implementierung führt eine ungültige Zeitzone zu einem Fehler:
HTTP/1.1 400 Bad Request
Spezifikationen
Specification |
---|
Unknown specification # section-2 |
Siehe auch
Preference-Applied
- Prefer-Header auf docs.oasis-open.org
- Prefer-Header auf docs.postgrest.org