Cette page a été traduite à partir de l'anglais par la communauté.Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.
En-tête Prefer
L'en-tête HTTPPrefer permet aux client·e·s d'indiquer des préférences pour des comportements spécifiques du serveur lors du traitement d'une requête.
Note :Les navigateurs ne gèrent pas les en-têtesPrefer etPreference-Applied : ils sont utilisés dans des clients personnalisés, spécifiques à l'implémentation.Assurez-vous que le client et le serveur prennent en charge cet en-tête avant de l'utiliser en production.
Les serveurs doivent ignorer silencieusement les préférences qu'ils ne prennent pas en charge, comme si l'en-tête n'était pas présent.
| Type d'en-tête | En-tête de requête |
|---|---|
| En-tête de requête interdit | Non |
Syntaxe
Prefer: <preference>, <preference>, ...Directives
respond-asyncLe client préfère un traitement asynchrone.Par exemple, le serveur peut répondre avec
202 Acceptedindiquant que la requête a été acceptée, accompagné de l'en-têteLocationcontenant une URL que le client peut utiliser pour suivre l'état du traitement.return=minimalDemande au serveur de retourner un contenu minimal (une réponse contenant uniquement les en-têtes).
return=representationDemande une représentation complète de la ressource dans la réponse.
wait=<seconds>Le temps dans lequel le client attend que le serveur fournisse une réponse, à partir du moment où la requête a été reçue.Si la préférence
respond-asyncest également fournie, le serveur doit répondre de façon asynchrone si le traitement dépasse le temps d'attente.Sinon, le serveur doit considérer que le client abandonnera après le temps indiqué (le comportement dépend de l'implémentation du serveur).handling=lenientLe client souhaite que le serveur applique une validation et une gestion des erreurs souples lors du traitement de la requête.
handling=strictLe client souhaite que le serveur applique une validation et une gestion des erreurs strictes lors du traitement de la requête.
- Préférence personnalisée
Les fournisseurs ou applications peuvent définir leurs propres préférences selon leurs besoins.Par exemple :
Prefer: timezone=America/Los_Angeles.
Exemples
Demander une réponse minimale
La requête suivante demande une réponse minimale.Il s'agit généralement d'une réponse contenant uniquement les en-têtes (par opposition àreturn=representation où une représentation est incluse dans le corps de la réponse) :
POST /resource HTTP/1.1Host: exemple.comContent-Type: application/jsonPrefer: return=minimal{"id":123, "name": "abc"}Le serveur répond avec201, mais n'inclut aucun corps de réponse.L'en-têteLocation contient une URL indiquant l'emplacement de la ressource nouvellement créée.Il n'est pas nécessaire d'inclure un en-têtePreference-Applied car l'absence de corps de réponse est évidente :
HTTP/1.1 201 CreatedLocation: /resource?id=123Demander un traitement asynchrone
Cet exemple demande au serveur de démarrer une tâche de traitement asynchrone :
POST /process HTTP/1.1Host: exemple.comPrefer: respond-async{ "task": "check-broken-links"}Le serveur répond avec202 Accepted indiquant que la requête a été acceptée et n'a pas encore été exécutée de façon asynchrone.Un en-têteLocation pointe vers un moniteur de statut représentant l'état du traitement :
HTTP/1.1 202 AcceptedLocation: http://exemple.com/tasks/123/statusFournir plusieurs préférences
La requête suivante inclut deux préférences ;timezone=Jupiter/Red_Spot indique une préférence de fuseau horaire pour le client, ethandling=strict pour strict validation :
GET /events HTTP/1.1Host: exemple.comPrefer: handling=strict, timezone=Jupiter/Red_SpotDans cette implémentation, un fuseau horaire invalide provoquera une erreur :
HTTP/1.1 400 Bad RequestSpécifications
| Specification |
|---|
| Prefer Header for HTTP # section-2 |
Voir aussi
- L'en-tête
Preference-Applied - L'en-tête Prefer(angl.) sur docs.oasis-open.org
- L'en-tête Prefer(angl.) sur docs.postgrest.org