En-têtes HTTP personnalisés: conventions de dénomination
Plusieurs de nos utilisateurs nous ont demandé d'inclure des données relatives à leur compte dans les en-têtes HTTP des demandes que nous leur envoyons, ou même les réponses qu'ils obtiennent de notre API. . Quelle est la convention générale pour ajouter des en-têtes HTTP personnalisés, en termes de nommage, format ... etc.
En outre, n'hésitez pas à publier toute utilisation intelligente de ceux-ci sur le Web. Nous essayons de mettre en œuvre cela en utilisant ce qui est le mieux en tant que cible :)
En juin 2012, l'abandon de la recommandation d'utiliser le préfixe "X-" est devenu officiel en tant que RFC 6648 . Vous trouverez ci-dessous des références pertinentes:
3. Recommandations pour les créateurs de nouveaux paramètres
...
- NE DEVRAIT PAS préfixer leurs noms de paramètres avec "X-" ou des constructions similaires.
4. Recommandations pour les concepteurs de protocoles
...
NE DEVRAIT PAS interdire l’enregistrement de paramètres avec un préfixe "X" ou des constructions similaires.
NE DOIT PAS stipuler qu'un paramètre avec un préfixe "X" ou des constructions similaires doit être compris comme non standard.
NE DOIT PAS stipuler qu'un paramètre sans préfixe "X" ou des constructions similaires doit être compris comme normalisé.
Notez que "NE DEVRAIT PAS" ("déconseillé") n'est pas la même chose que "NE DOIT PAS" ("interdit"), voir aussi RFC 2119 pour une autre spécification sur ces mots clés. En d'autres termes, vous pouvez continuer à utiliser les en-têtes avec préfixe "X", mais ce n'est pas recommandé et vous ne pouvez pas les documenter comme s'il s'agissait d'une norme publique.
En juin 2011, le premier brouillon de l'IETF a été posté sur déconseiller la recommandation d'utiliser le préfixe "X-" pour les non en-têtes standard. La raison en est que lorsque les en-têtes non standard précédés de "X-" deviennent standard, la suppression du préfixe "X-" interrompt la compatibilité avec les versions antérieures, forçant les protocoles d'application à prendre en charge les deux noms (par exemple, _x-gzip_ & gzip sont maintenant équivalents). La recommandation est donc de simplement les nommer de manière judicieuse sans le préfixe "X-".
La recommandation est était pour commencer leur nom avec "X-". Par exemple. X-Forwarded-For , X-Requested-With . Ceci est également mentionné en a.o. section 5 de RFC 2047 .
La question mérite d'être relue. La question posée n’est pas la même chose que les préfixes de fournisseur dans les propriétés CSS, où il est approprié de penser au support et aux normes officielles du fournisseur. La question posée est plus proche du choix d’un nom de paramètre de requête d’URL. Personne ne devrait se soucier de ce qu'ils sont. Mais espacer les noms des noms personnalisés est une chose à faire parfaitement valide - et commune - et correcte.
Justification:
Il s’agit de conventions entre les développeurs pour les en-têtes personnalisés propres à l’application - " pertinentes". sur leur compte "- qui n’a rien à voir avec des fournisseurs, des organismes de normalisation ou des protocoles à mettre en œuvre par des tiers, sauf que le développeur en question doit simplement éviter les en-têtes qui pourraient en avoir autre utilisation prévue par les serveurs, les mandataires ou les clients. Pour cette raison, les exemples "X-Gzip/Gzip" et "X-Forwarded-For/Forwarded-For" donnés sont sans objet. La question posée concerne les conventions dans le contexte d’une API privée, semblables aux conventions de dénomination des paramètres de requête d’URL. C'est une question de préférence et d'espacement des noms; les préoccupations concernant le "X-ClientDataFoo" pris en charge par tout proxy ou fournisseur sans le "X" sont clairement mal placées.
Le préfixe "X-" n'a rien de spécial ni de magique, mais il est utile de préciser qu'il s'agit d'un en-tête personnalisé. En fait, les RFC-6648 et autres aident à renforcer l'utilisation d'un préfixe "X", car, à mesure que les fournisseurs de clients et de serveurs HTTP abandonnent ce préfixe, votre application spécifique, votre API privée, vos données personnelles. le mécanisme de passe devient de mieux en mieux isolé contre les collisions entre espaces de noms avec le petit nombre de noms d'en-tête réservés officiels. Cela dit, ma préférence et ma recommandation personnelles sont d'aller plus loin et de le faire, par exemple. "X-ACME-ClientDataFoo" (si votre société de widgets est "ACME").
À mon humble avis, les spécifications de l'IETF ne sont pas suffisamment spécifiques pour répondre à la question du PO, car elles ne permettent pas de distinguer des cas d'utilisation complètement différents: les développeurs d'applications qui transmettent des chaînes spécifiques à l'application vers/depuis le client et le serveur. La spécification ne concerne que l'ancien, (A). La question ici est de savoir s’il existe des conventions pour (B). Il y a. Ils impliquent de regrouper les paramètres par ordre alphabétique et de les séparer des nombreux en-têtes de type (A) pertinents pour les normes. L'utilisation du préfixe "X" ou "X-ACME-" est pratique et légitime pour (B) et n'entre pas en conflit avec (A). Plus les vendeurs cessent d'utiliser "X-" pour (A), plus les (B) deviendront clairement distincts.
Exemple:
Google (qui a un peu de poids dans les divers organismes de normalisation) est - à ce jour, 20141102 dans cette légère modification à ma réponse - utilise actuellement "X-Mod-Pagespeed" pour indiquer la version de leur module Apache impliqué dans la transformation d'une réponse donnée. Quelqu'un suggère-t-il réellement que Google utilise "Mod-Pagespeed", sans le "X-", et/ou demande à l'IETF de bénir son utilisation?
Résumé:
Si vous utilisez des en-têtes HTTP personnalisés (en tant qu’alternative parfois appropriée aux cookies) dans votre application pour transmettre des données vers/depuis votre serveur, ces en-têtes NE SONT, explicitement, PAS destinés à être utilisés en dehors du serveur. Le contexte de votre application, en les espaçant de nom avec un préfixe "X-" ou "X-FOO-" est une convention raisonnable et commune.
Le format des en-têtes HTTP est défini dans la spécification HTTP. Je vais parler de HTTP 1.1, pour lequel la spécification est RFC 2616 . Dans la section 4.2, "En-têtes de message", la structure générale d'un en-tête est définie:
message-header = field-name ":" [ field-value ]
field-name = token
field-value = *( field-content | LWS )
field-content = <the OCTETs making up the field-value
and consisting of either *TEXT or combinations
of token, separators, and quoted-string>
Cette définition repose sur deux piliers principaux, le jeton et le texte. Les deux sont définis dans la section 2.2, "Règles de base". Le jeton est:
token = 1*<any CHAR except CTLs or separators>
À son tour, reposant sur CHAR, CTL et des séparateurs:
CHAR = <any US-ASCII character (octets 0 - 127)>
CTL = <any US-ASCII control character
(octets 0 - 31) and DEL (127)>
separators = "(" | ")" | "<" | ">" | "@"
| "," | ";" | ":" | "\" | <">
| "/" | "[" | "]" | "?" | "="
| "{" | "}" | SP | HT
TEXT est:
TEXT = <any OCTET except CTLs,
but including LWS>
Où LWS est un espace blanc linéaire, dont la définition ne sera pas reproduite, et OCTET est:
OCTET = <any 8-bit sequence of data>
Une note accompagne la définition:
The TEXT rule is only used for descriptive field contents and values
that are not intended to be interpreted by the message parser. Words
of *TEXT MAY contain characters from character sets other than ISO-
8859-1 [22] only when encoded according to the rules of RFC 2047
[14].
Donc, deux conclusions. Tout d’abord, il est clair que l’en-tête name doit être composé d’un sous-ensemble de ASCII caractères - des caractères alphanumériques, de la ponctuation, pas beaucoup autre. Deuxièmement, il n'y a rien dans la définition d'un en-tête valeur qui le limite à ASCII ou exclut les caractères de 8 bits: c'est explicitement composé d'octets, avec uniquement des caractères de contrôle interdits (notez que CR et LF sont considérés comme des contrôles). De plus, le commentaire sur la production TEXT implique que les octets doivent être interprétés comme étant dans l'ISO-8859-1 et qu'il existe un mécanisme de codage (qui est horrible, incidemment) pour représenter des caractères en dehors de ce codage.
Donc, pour répondre à @BalusC en particulier, il est évident que, conformément à la spécification, les valeurs d'en-tête sont définies dans ISO-8859-1. J'ai envoyé des caractères high-8859-1 (en particulier des voyelles accentuées utilisées en français) dans un en-tête de Tomcat, et je les ai fait interpréter correctement par Firefox. Donc, dans une certaine mesure, cela fonctionne dans la pratique comme dans la théorie. (bien qu'il s'agisse d'un en-tête Location, qui contient une URL et que ces caractères ne sont pas autorisés dans les URL, il était donc illégal, mais sous une règle différente!).
Cela dit, je ne compterais pas sur ISO-8859-1 pour l’ensemble des serveurs, des mandataires et des clients, je me contenterais donc de ASCII pour la programmation défensive.
Modifier, ou plus correctement, ajouter des en-têtes HTTP supplémentaires est un excellent outil de débogage de code.
Lorsqu'une demande d'URL renvoie une redirection ou une image, il n'y a pas de "page" html sur laquelle écrire temporairement les résultats du code de débogage - du moins pas celle qui est visible dans un navigateur.
Une approche consiste à écrire les données dans un fichier journal local et à afficher ce fichier ultérieurement. Une autre consiste à ajouter temporairement des en-têtes HTTP reflétant les données et les variables en cours de débogage.
J'ajoute régulièrement des en-têtes HTTP supplémentaires, tels que X-fubar-somevar: ou X-test-someresult: pour tester des éléments - et j'ai trouvé de nombreux bogues qui, autrement, auraient été très difficiles à localiser.
Le registre de noms de champs d'en-tête est défini dans RFC3864 , et il n'y a rien de spécial avec "X-".
Autant que je sache, il n’existe aucune directive pour les en-têtes privés; en cas de doute, évitez-les. Ou jetez un coup d'œil au framework d'extension HTTP ( RFC 2774 ).
Il serait intéressant de mieux comprendre le cas d'utilisation. pourquoi les informations ne peuvent-elles pas être ajoutées au corps du message?
RFC6648 vous recommandons de supposer que votre en-tête personnalisé "peut devenir normalisé, public, couramment déployé ou utilisable pour plusieurs implémentations." Par conséquent, il est recommandé de ne pas le préfixer avec "X" ou des constructions similaires.
Cependant, il existe une exception "lorsqu'il est extrêmement improbable que [votre en-tête] soit jamais normalisé". Pour de tels en-têtes "spécifiques à l'implémentation et à usage privé", la RFC indique qu'un espace de noms tel qu'un préfixe de fournisseur est justifié.