Intestazioni HTTP personalizzate: convenzioni di denominazione

Molti dei nostri utenti ci hanno chiesto di includere i dati relativi al loro account nelle intestazioni HTTP delle richieste che inviamo loro, o anche le risposte che ricevono dalla nostra API. Qual è la convenzione generale per aggiungere intestazioni HTTP personalizzate, in termini di denominazione , formato ... ecc.

Inoltre, sentiti libero di pubblicare qualsiasi utilizzo intelligente di questi che ti sei imbattuto sul web; Stiamo cercando di implementare questo usando ciò che è meglio là fuori come obiettivo :)

La raccomandazione è stata di iniziare il loro nome con la "X". Ad esempio X-Forwarded-For, X-Requested-With. Questo è anche menzionato nella sezione 5 di RFC 2047 .

Aggiornamento 1 : a giugno 2011, è stata pubblicata la prima bozza IETF per deprecare la raccomandazione di utilizzare il prefisso "X-" per intestazioni non standard. Il motivo è che quando le intestazioni non standard con prefisso "X-" diventano standard, la rimozione del prefisso "X-" interrompe la compatibilità con le versioni precedenti, costringendo i protocolli applicativi a supportare entrambi i nomi (ad esempio, x-gzipe gzipora sono equivalenti). Quindi, la raccomandazione ufficiale è di nominarli sensibilmente senza il prefisso "X-".

Aggiornamento 2 : a giugno 2012, la deprecazione della raccomandazione di utilizzare il prefisso "X-" è diventata ufficiale come RFC 6648 . Di seguito sono citate le citazioni rilevanti:

3. Consigli per i creatori di nuovi parametri

...

3. NON DOVREBBE anteporre i nomi dei loro parametri con "X-" o costrutti simili.

4. Raccomandazioni per i progettisti di protocollo

...

4. NON DOVREBBE vietare la registrazione di parametri con un prefisso "X-" o costrutti simili.

5. NON DEVE stipulare che un parametro con un prefisso "X-" o costrutti simili deve essere inteso come non standardizzato.

6. NON DEVE stipulare che un parametro senza prefisso "X-" o costrutti simili debba essere inteso come standardizzato.

Nota che "NON DOVREBBE" ("scoraggiato") non è lo stesso di "NON DEVE" ("proibito"), vedi anche RFC 2119 per un'altra specifica su tali parole chiave. In altre parole, puoi continuare a usare le intestazioni con prefisso "X-", ma non è più ufficialmente raccomandato e potresti sicuramente non documentarle come se fossero standard pubblici.

Riepilogo :

• la raccomandazione ufficiale è semplicemente nominarli sensibilmente senza il prefisso "X-"
• puoi continuare a usare le intestazioni con prefisso "X-", ma non è più ufficialmente raccomandato e potresti sicuramente non documentarle come se fossero standard pubblici

La domanda deve essere riletta. La vera domanda posta non è simile ai prefissi dei fornitori nelle proprietà CSS, dove è appropriato pensare al futuro e al supporto del fornitore e agli standard ufficiali. La vera domanda posta è più simile alla scelta dei nomi dei parametri della query URL. A nessuno dovrebbe interessare quello che sono. Ma la spaziatura dei nomi di quelli personalizzati è una cosa perfettamente valida - e comune e corretta - da fare.

Razionale:
si tratta di convenzioni tra sviluppatori per intestazioni personalizzate e specifiche dell'applicazione - " dati rilevanti per il loro account " - che non hanno nulla a che fare con fornitori, organismi di standardizzazione o protocolli che devono essere implementati da terzi, tranne che lo sviluppatore in questione deve semplicemente evitare i nomi di intestazione che potrebbero avere altri usi previsti da server, proxy o client. Per questo motivo, gli esempi "X-Gzip / Gzip" e "X-Forwarded-For / Forwarded-For" sono controversi. La domanda posta riguarda le convenzioni nel contesto di un'API privata, simile alle convenzioni di denominazione dei parametri della query URL. È una questione di preferenza e spaziatura dei nomi; dubbi sul fatto che "X-ClientDataFoo" sia supportato da qualsiasi proxy o fornitore senza la "X"

Non c'è niente di speciale o magico nel prefisso "X-", ma aiuta a chiarire che si tratta di un'intestazione personalizzata. In effetti, RFC-6648 e altri aiutano a sostenere il caso dell'uso di un prefisso "X-", perché - poiché i fornitori di client e server HTTP abbandonano il prefisso - l'API privata, l'API specifica, i dati personali- il meccanismo di passaggio sta diventando ancora più isolato dalle collisioni dello spazio dei nomi con il piccolo numero di nomi di intestazione riservati ufficiali. Detto questo, la mia preferenza personale e la mia raccomandazione è di fare un passo avanti e fare ad esempio "X-ACME-ClientDataFoo" (se la tua compagnia di widget è "ACME").

IMHO le specifiche IETF non sono sufficientemente specifiche per rispondere alla domanda del PO, perché non riescono a distinguere tra casi d'uso completamente diversi: (A) fornitori che introducono nuove funzionalità applicabili a livello globale come "Forwarded-For" da un lato, rispetto a (B) sviluppatori di app che passano stringhe specifiche dell'app a / da client e server. La specifica riguarda solo la prima, (A). La domanda qui è se ci sono convenzioni per (B). Ci sono. Coinvolgono il raggruppamento dei parametri in ordine alfabetico e la loro separazione dalle numerose intestazioni di tipo (A) rilevanti per gli standard. L'uso del prefisso "X-" o "X-ACME-" è conveniente e legittimo per (B) e non è in conflitto con (A). Più fornitori smettono di usare "X-" per (A), più chiaramente diventeranno quelli (B).

Esempio:
Google (che ha un po 'di peso nei vari organismi di standardizzazione) sta - ad oggi, 20141102 in questa leggera modifica alla mia risposta - attualmente utilizzando "X-Mod-Pagespeed" per indicare la versione del loro modulo Apache coinvolto nella trasformazione di una determinata risposta. Qualcuno sta davvero suggerendo che Google dovrebbe usare "Mod-Pagespeed", senza la "X-", e / o chiedere all'IETF di benedire il suo utilizzo?

Riepilogo:
se stai usando intestazioni HTTP personalizzate (come alternativa talvolta appropriata ai cookie) all'interno della tua app per trasmettere dati al / dal tuo server, e queste intestazioni NON sono esplicitamente destinate a essere utilizzate al di fuori del contesto del tuo applicazione, spaziandoli con un prefisso "X-" o "X-FOO-" è una convenzione ragionevole e comune.

Il formato per le intestazioni HTTP è definito nelle specifiche HTTP. Parlerò di HTTP 1.1, per il quale la specifica è RFC 2616 . Nella sezione 4.2, "Intestazioni dei messaggi", viene definita la struttura generale di un'intestazione:

   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>

Questa definizione si basa su due pilastri principali, token e TEXT. Entrambi sono definiti nella sezione 2.2, "Regole di base". Il token è:

   token          = 1*<any CHAR except CTLs or separators>

A sua volta appoggiato su CHAR, CTL e separatori:

   CHAR           = <any US-ASCII character (octets 0 - 127)>

   CTL            = <any US-ASCII control character
                    (octets 0 - 31) and DEL (127)>

   separators     = "(" | ")" | "<" | ">" | "@"
                  | "," | ";" | ":" | "\" | <">
                  | "/" | "[" | "]" | "?" | "="
                  | "{" | "}" | SP | HT

TESTO è:

   TEXT           = <any OCTET except CTLs,
                    but including LWS>

Dove LWS è uno spazio bianco lineare, la cui definizione non riprodurrò, e OCTET è:

   OCTET          = <any 8-bit sequence of data>

C'è una nota che accompagna la definizione:

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].

Quindi, due conclusioni. Innanzitutto, è chiaro che il nome dell'intestazione deve essere composto da un sottoinsieme di caratteri ASCII: alfanumerici, alcuni segni di punteggiatura, non molto altro. In secondo luogo, non esiste nulla nella definizione di un valore di intestazione che lo limiti a ASCII o esclude caratteri a 8 bit: è esplicitamente composto da ottetti, con solo caratteri di controllo esclusi (si noti che CR e LF sono considerati controlli). Inoltre, il commento sulla produzione TEXT implica che gli ottetti devono essere interpretati come in ISO-8859-1 e che esiste un meccanismo di codifica (che è orribile, per inciso) per rappresentare personaggi al di fuori di quella codifica.

Quindi, per rispondere a @BalusC in particolare, è abbastanza chiaro che secondo le specifiche, i valori di intestazione sono in ISO-8859-1. Ho inviato caratteri alti 8859-1 (in particolare alcune vocali accentate usate in francese) in un'intestazione di Tomcat e li ho interpretati correttamente da Firefox, quindi, in una certa misura, funziona sia in pratica che in teoria (sebbene questa fosse un'intestazione Location, che contiene un URL, e questi caratteri non sono legali negli URL, quindi questo era in realtà illegale, ma con una regola diversa!).

Detto questo, non farei affidamento sul fatto che ISO-8859-1 funzioni su tutti i server, i proxy e i client, quindi mi atterrerei all'ASCII come una questione di programmazione difensiva.

RFC6648 consiglia di presumere che l'intestazione personalizzata "potrebbe diventare standardizzata, pubblica, comunemente distribuita o utilizzabile su più implementazioni". Pertanto, si consiglia di non prefissarlo con "X-" o costrutti simili.

Tuttavia, esiste un'eccezione "quando è estremamente improbabile che [la tua intestazione] sia mai standardizzata". Per tali intestazioni "specifiche dell'implementazione e di uso privato", la RFC afferma che uno spazio dei nomi come un prefisso del fornitore è giustificato.

La modifica o, più correttamente, l' aggiunta di ulteriori intestazioni HTTP è un ottimo strumento di debug del codice se non altro.

Quando una richiesta URL restituisce un reindirizzamento o un'immagine, non esiste una "pagina" html in cui scrivere temporaneamente i risultati del codice di debug, almeno non visibile in un browser.

Un approccio consiste nel scrivere i dati in un file di registro locale e visualizzarlo in un secondo momento. Un altro è aggiungere temporaneamente le intestazioni HTTP che riflettano i dati e le variabili in fase di debug.

Aggiungo regolarmente ulteriori intestazioni HTTP come X-fubar-somevar: o X-testing-someresult: per testare le cose - e ho trovato molti bug che altrimenti sarebbero stati molto difficili da rintracciare.

Il registro dei nomi dei campi di intestazione è definito in RFC3864 e non c'è niente di speciale con "X-".

Per quanto ne so, non ci sono linee guida per le intestazioni private; nel dubbio, evitali. Oppure dai un'occhiata al HTTP Extension Framework ( RFC 2774 ).

Sarebbe interessante capire di più del caso d'uso; perché non è possibile aggiungere le informazioni al corpo del messaggio?