Der HTTP-Prefer-Header ermöglicht es Clients, Präferenzen für spezifische Serververhaltensweisen während der Anfragverarbeitung anzugeben.

Syntax

Prefer: <preference>, <preference>, ...

Direktiven

respond-async

Der Client bevorzugt asynchrone Verarbeitung.Zum Beispiel könnte der Server mit einer202 Accepted-Antwort antworten, die angibt, dass die Anfrage angenommen wurde, zusammen mit demLocation-Header, der eine URL enthält, die der Client verwenden kann, um den Status der Verarbeitung zu überwachen.

return=minimal

Fordert an, dass der Server minimalen Inhalt zurückgibt (eine Antwort nur mit Headern).

return=representation

Fordert eine vollständige Ressourcenrepräsentation in der Antwort an.

wait=<seconds>

Die Zeit, innerhalb derer der Client erwartet, dass der Server eine Antwort liefert, ab dem Zeitpunkt, an dem die Anfrage empfangen wurde.Wenn auch dierespond-async-Präferenz angegeben ist, sollte der Server asynchron antworten, wenn die Verarbeitung der Anfrage die Wartezeit überschreitet.Andernfalls sollte der Server davon ausgehen, dass der Client nach derwait-Zeit ein Timeout auslöst (das Antwortverhalten hängt von der Serverimplementierung ab).

handling=lenient

Der Client wünscht sich, dass der Server eine nachsichtige Validierung und Fehlerbehandlung bei der Verarbeitung der Anfrage anwendet.

handling=strict

Der Client wünscht sich, 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 Anforderungen zu erfüllen.Zum BeispielPrefer: timezone=America/Los_Angeles.

Beispiele

Minimalantwort anfordern

Die folgende Anfrage fragt nach einer Minimalantwort.Dies ist typischerweise eine Antwort nur mit Headern (im Gegensatz zureturn=representation, wo eine Repräsentation im Antwortkörper enthalten ist):

POST /resource HTTP/1.1Host: example.comContent-Type: application/jsonPrefer: return=minimal{"id":123, "name": "abc"}

Der Server antwortet mit einer201, enthält jedoch keinen Antwortkörper.DerLocation-Header enthält eine URL mit dem Standort der neu erstellten Ressource.Es ist nicht notwendig, einenPreference-Applied-Header zu enthalten, da das Fehlen eines Antwortkörpers offensichtlich ist:

HTTP/1.1 201 CreatedLocation: /resource?id=123

Asynchrone Verarbeitung anfordern

Dieses Beispiel fordert den Server auf, eine asynchrone Verarbeitung zu starten:

POST /process HTTP/1.1Host: example.comPrefer: respond-async{  "task": "check-broken-links"}

Der Server antwortet mit einer202 Accepted-Antwort, die angibt, dass die Anfrage akzeptiert wurde und die Ausführung noch nicht asynchron abgeschlossen ist.EinLocation-Header zeigt auf einen Statusmonitor, der den Zustand der Verarbeitung darstellt:

HTTP/1.1 202 AcceptedLocation: http://example.com/tasks/123/status

Mehrere Präferenzen angeben

Die folgende Anfrage enthält zwei Präferenzen;timezone=Jupiter/Red_Spot, das eine Zeitzonen-Präferenz für den Client angibt, undhandling=strict für strikte Validierung:

GET /events HTTP/1.1Host: example.comPrefer: handling=strict, timezone=Jupiter/Red_Spot

In dieser Implementierung löst eine ungültige Zeitzone einen Fehler aus:

HTTP/1.1 400 Bad Request

Spezifikationen

Siehe auch

• Preference-Applied
• Prefer-Header auf docs.oasis-open.org
• Prefer-Header auf docs.postgrest.org