Niestandardowe nagłówki HTTP: konwencje nazewnictwa

1113

Kilku naszych użytkowników poprosiło nas o uwzględnienie danych dotyczących ich konta w nagłówkach HTTP wysyłanych przez nas żądań, a nawet odpowiedzi otrzymywanych z naszego interfejsu API. Jaka jest ogólna konwencja dodawania niestandardowych nagłówków HTTP pod względem nazewnictwa , formatu ... itd.

Zachęcamy również do publikowania wszelkich inteligentnych zastosowań tych, na które natknąłeś się w Internecie; Staramy się to zaimplementować, wykorzystując to, co najlepsze jako cel :)

Julien Genestoux
źródło
25
Należy pamiętać, że zapory ogniowe mogą usuwać pola nagłówka odpowiedzi. Niektóre usuwają wszystko, co nie jest wymienione w RFC 2616 (czerwiec 1999, HTTP 1.1). Po stronie klienta nadal powinno być możliwe korzystanie bez nowych pól.
stesch
5
Należy zauważyć, że komentarz @stesch nie stosuje się przy użyciu protokołu HTTP S .
code_dredd
1
Pamiętaj, że komentarz @code_dredd to miejska legenda. Zapory ogniowe mogą filtrować zawartość HTTPS. Zobacz howtoforge.com/filtering-https-traffic-with-squid i watchguard.com/help/docs/wsm/xtm_11/en-us/content/en-us/…
stesch
@stesch Biorąc pod uwagę, że Twój artykuł zasadniczo zmienia serwer proxy w coś podobnego do MiTM (wymaga szyfrowanego połączenia klienta, a następnie tworzy nowe), to na pewno możesz zrobić prawie wszystko, ale fakt ten neguje szyfrowanie z PoV b / proxy c odszyfrowuje samą zawartość klienta. W takim przypadku z PoV serwera proxy jest tak, jakbyś nie używał HTTPS na pierwszym miejscu ...
code_dredd

Odpowiedzi:

1171

Zalecenie jest to , aby rozpocząć swoją nazwę z „X-”. Np X-Forwarded-For, X-Requested-With. Jest to również wspomniane w sekcji 5 RFC 2047 .


Aktualizacja 1 : W czerwcu 2011 r. Opublikowano pierwszy projekt IETF, który zastąpił zalecenie używania prefiksu „X-” w przypadku niestandardowych nagłówków. Powodem jest to, że gdy niestandardowe nagłówki z prefiksem „X-” stają się standardem, usunięcie prefiksu „X-” psuje kompatybilność wsteczną, zmuszając protokoły aplikacji do obsługi obu nazw (np. x-gzipI gzipsą teraz równoważne). Oficjalna rekomendacja polega więc na rozsądnym nazwaniu ich bez prefiksu „X-”.


Aktualizacja 2 : W czerwcu 2012 r. Wycofanie zalecenia używania prefiksu „X-” stało się oficjalne jako RFC 6648 . Poniżej znajdują się cytaty mające znaczenie:

3. Zalecenia dla twórców nowych parametrów

...

  1. NIE WOLNO poprzedzać ich nazw parametrami „X-” lub podobnymi konstrukcjami.

4. Zalecenia dla projektantów protokołów

...

  1. NIE WOLNO blokować rejestracji parametrów z przedrostkiem „X-” lub podobnymi konstrukcjami.

  2. NIE WOLNO określać, że parametr z przedrostkiem „X-” lub podobnymi konstrukcjami należy rozumieć jako niestandardowy.

  3. NIE WOLNO określać, że parametr bez przedrostka „X-” lub podobnych konstrukcji należy rozumieć jako znormalizowany.

Zauważ, że „NIE POWINNY” („zniechęcony”) nie jest tym samym, co „NIE MUSI” („zabronione”), zobacz także RFC 2119, aby uzyskać inną specyfikację tych słów kluczowych. Innymi słowy, możesz nadal używać nagłówków „X-”, ale nie jest to już oficjalnie zalecane i na pewno nie udokumentujesz ich tak, jakby były standardem publicznym.


Podsumowanie :

  • oficjalna rekomendacja to rozsądne nazwanie ich bez prefiksu „X-”
  • możesz nadal używać prefiksów „X-”, ale nie jest to już oficjalnie zalecane i na pewno nie udokumentujesz ich tak, jakby były standardem publicznym
BalusC
źródło
306
Podobnie jak wiele dzieci, które nigdy nie zostaną profesjonalnymi sportowcami, tak wiele niestandardowych nagłówków nigdy nie stanie się standardem. Mam skłonność do trzymania „X-” na nich.
G-Mac
19
@ G-Mac uzgodniony. Istnieje tak wiele niestandardowych nagłówków, które nigdy nie będą znormalizowane. W tych kilku przypadkach łatwo jest po prostu edytować kod od if (header == "x-gzip")do if (header == "x-gzip" || header == "gzip"). Jeśli chodzi o twoją analogię, oto inna: to jak wojsko mówi: „Och, zmiana kogoś z szeregowego na generalnego jest kłopotliwa. Odtąd wszyscy jesteście generałami. Teraz nie musimy wykonywać tyle pracy”
Cole Johnson
24
@ColeJohnson Nie jestem pewien, czy ta analogia działa. Problem polega na tym, że nie ma centralnego punktu, w którym można zmienić nazwę. Każdy fragment kodu, który oczekuje x-gzip, musi teraz zostać zmieniony lub stary nagłówek musi być nadal używany oprócz nowego. Lepiej jest iść z RFC 6648.
vinod
4
@Vinod tak. Ma to sens, ale zaproponowano tak wiele standardów, które nigdy nie ujrzą światła dziennego. Na pewno dla typów plików; upuść X-prefiks. Jestem temu przeciwny, ale zrób to. W przypadku nagłówków OTOH nie upuszczaj go. Ułatwia to patrzenie i mówienie: „och, to jest niestandardowe; mogę to zignorować„ vs ”są te niestandardowe X-nagłówki, a potem jest taki, którego nie rozpoznaję; czy mogę to bezpiecznie zignorować?”
Cole Johnson
21
Chociaż ton cotygodniowej odpowiedzi jest niepotrzebnie defensywny, uważam, że ma rację, a jego argument rozwiązuje problem przedstawiony w tym wątku komentarza. Krótko mówiąc, nie próbuj określać, czy nagłówek „ukończy”, czy nie; zamiast tego określ, czy jest to nagłówek prywatny czy publiczny (specyficzny dla aplikacji czy „ogólny” / „globalny”). W przypadku nagłówków prywatnych opcjonalnie użyj, X-aby nie kolidować z nagłówkami publicznymi (dzięki RFC6648, który zajmuje się nagłówkami publicznymi), a ponadto zdecydowanie użyj dowolnego prywatnego prefiksu. W przypadku nagłówków publicznych nie używaj X-w żadnych okolicznościach.
tne
535

Pytanie wymaga ponownego przeczytania. Rzeczywiste pytanie nie jest podobne do prefiksów dostawcy we właściwościach CSS, gdzie właściwe jest zapewnienie przyszłości i myślenie o wsparciu dostawcy i oficjalnych standardach. Rzeczywiste pytanie jest bardziej zbliżone do wybierania nazw parametrów zapytań URL. Nikt nie powinien dbać o to, czym są. Ale odstępy między nazwami niestandardowych są całkowicie poprawną - i powszechną i poprawną - rzeczą do zrobienia.

Uzasadnienie:
Chodzi o konwencje między programistami dotyczące niestandardowych, specyficznych dla aplikacji nagłówków - „ danych istotnych dla ich konta ” - które nie mają nic wspólnego z dostawcami, organami normalizacyjnymi lub protokołami, które mają zostać wdrożone przez strony trzecie, z wyjątkiem tego, że programista w tym pytaniu należy po prostu unikać nazw nagłówków, które mogą mieć inne zamierzone zastosowanie przez serwery, serwery proxy lub klientów. Z tego powodu podane przykłady „X-Gzip / Gzip” i „X-Forwarded-For / Forwarded-For” są dyskusyjne. Zadane pytanie dotyczy konwencji w kontekście prywatnego interfejsu API, podobnie jak konwencje nazewnictwa parametrów zapytań URL. Jest to kwestia preferencji i odstępów między nazwami; obawy związane z obsługą „X-ClientDataFoo” przez dowolnego proxy lub dostawcę bez „X”

W prefiksie „X-” nie ma nic specjalnego ani magicznego, ale pomaga wyjaśnić, że jest to niestandardowy nagłówek. W rzeczywistości RFC-6648 i in. Pomagają usprawnić stosowanie prefiksu „X-”, ponieważ - ponieważ dostawcy klientów HTTP i serwerów rezygnują z prefiksu - specyficzny dla aplikacji, prywatny interfejs API, dane osobowe- mechanizm przekazywania staje się jeszcze lepiej izolowany przed kolizjami przestrzeni nazw z niewielką liczbą oficjalnych zastrzeżonych nazw nagłówków. To powiedziawszy, moim osobistym upodobaniem i zaleceniem jest pójść o krok dalej i zrobić np. „X-ACME-ClientDataFoo” (jeśli twoją firmą zajmującą się widgetami jest „ACME”).

IMHO specyfikacja IETF nie jest wystarczająco specyficzna, aby odpowiedzieć na pytanie PO, ponieważ nie rozróżnia całkowicie różnych przypadków użycia: (A) dostawcy wprowadzają nowe globalne funkcje, takie jak „Forwarded-For” z jednej strony, a (B) twórcy aplikacji przekazujący ciągi specyficzne dla aplikacji do / z klienta i serwera. Specyfikacja dotyczy tylko tego pierwszego, (A). Pytanie brzmi, czy istnieją konwencje dla (B). Tam są. Obejmują pogrupowanie parametrów alfabetycznie i oddzielenie ich od wielu nagłówków typu (A) istotnych dla standardów. Używanie przedrostka „X-” lub „X-ACME-” jest wygodne i uzasadnione dla (B) i nie powoduje konfliktu z (A). Im więcej dostawców przestanie używać „X-” dla (A), tym bardziej wyraźne będą te (B).

Przykład:
Google (którzy mają trochę wagi w różnych organach normalizacyjnych) - na dzień 20141102 w tej niewielkiej edycji mojej odpowiedzi - obecnie używają „X-Mod-Pagespeed”, aby wskazać wersję swojego modułu Apache zaangażowany w przekształcanie danej odpowiedzi. Czy ktoś naprawdę sugeruje, że Google powinien używać „Mod-Pagespeed” bez „X-” i / lub prosić IETF o błogosławieństwo jego użycia?

Podsumowanie:
jeśli używasz niestandardowych nagłówków HTTP (jako czasem odpowiedniej alternatywy dla plików cookie) w swojej aplikacji do przesyłania danych do / z serwera, a te nagłówki NIE są jawnie przeznaczone do użycia poza kontekstem twojego aplikacji, odstępy między nazwami z prefiksem „X-” lub „X-FOO-” są rozsądną i powszechną konwencją.

co tydzień
źródło
52
Byłbym wdzięczny, gdyby któryś z głosujących w moim komentarzu mógł wyjaśnić, która część mojej odpowiedzi jest dla nich nieodpowiednia. Nie dbam tak bardzo o moją reputację, ale jestem naprawdę ciekawy. Gdzie leży różnica zdań? Dzięki.
tydzień
56
Całkowicie zgadzam się z twoją odpowiedzią i jest to jedyna odpowiedź, która odpowiada na faktycznie zadane pytanie. Mówimy tutaj o niestandardowych, specyficznych dla aplikacji nagłówkach, nigdy nie podlegających standaryzacji w standardach HTTP. Czy istnieje wspólna konwencja dla tych, których ludzie używają? (np. może poprzedzić je „_”? tj .: („_ClientDataFoo”)
Marchy
14
Dzięki Marchy, tak, zaakceptowana odpowiedź nie odnosi się do zadanego pytania. Wycofanie IETF prefiksu „X-” dla niestandardowych (ale ogólnych) nagłówków nie ma znaczenia dla niestandardowych nagłówków specyficznych dla aplikacji, które nigdy nie będą standaryzowane. Aby odpowiedzieć na twoje pytanie, moim zdaniem i doświadczeniem (16 lat webdev), najlepszą konwencją jest użycie wyżej wspomnianego „X-ACME-ClientData”. „X-” bc to nie jest standard (i nigdy nie będzie, dlatego tutaj wycofanie IETF jest tutaj dyskusyjne), „ACME-”, aby nazwać go swoją firmą „ACME” lub określoną aplikacją, a „ClientData” może być dowolna semantyczna nazwa, którą lubisz. :)
tydzień
5
@DarrelMiller ... stąd zalecenie użycia X-ACMECO-WIDGET-FOO. Nalegam, aby w zadanym pytaniu OP użycie X- po prostu nie było przeciwwskazane przez RFC-6648 i tym podobne. Jeśli jesteś dostawcą frameworka, biblioteki lub modułu do użytku w projektach innych ludzi, to inna historia i zdecydowanie podążaj za tym RFC do T. Ale to tylko kwestia pojedynczych, jednorazowych aplikacji, gdzie niestandardowe specyficzne dla aplikacji konwencje nazewnictwa nagłówków są całkowicie prywatnymi interfejsami API. Jak kolidowaliby z imionami „wszystkich innych”? Czyje by to były?
tydzień
11
Naprawdę mam trochę problemów ze zrozumieniem rozumowania RFC. Przyznaję, że jeśli i kiedy parametr zostanie znormalizowany, będą dostępne zarówno wersje x, jak i inne. Jest to problem tylko wtedy, gdy zachowanie wersji x i innych niż x jest identyczne. Natknąłem się tutaj, ponieważ zamierzam dodać nagłówek „w imieniu” do mojego interfejsu API. Może kiedyś stać się publiczny (ponieważ jest to częsty przypadek użycia). Jeśli użyłem „On-Behalf-Of” i któregoś dnia dodadzą to jako standardowy nagłówek, jakie są szanse, że moja semantyka będzie identyczna ze standardową?
fool4jesus
62

Format nagłówków HTTP jest zdefiniowany w specyfikacji HTTP. Opowiem o HTTP 1.1, dla którego specyfikacja to RFC 2616 . W sekcji 4.2 „Nagłówki wiadomości” zdefiniowano ogólną strukturę nagłówka:

   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>

Ta definicja opiera się na dwóch głównych filarach: tokenie i TEKSTIE. Oba są zdefiniowane w sekcji 2.2, „Podstawowe zasady”. Token to:

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

Z kolei spoczywające na CHAR, CTL i separatorach:

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

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

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

TEKST to:

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

Gdzie LWS to liniowa biała przestrzeń, której definicji nie będę reprodukować, a OCTET to:

   OCTET          = <any 8-bit sequence of data>

Definicja zawiera notatkę:

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

Więc dwa wnioski. Po pierwsze, jasne jest, że nazwa nagłówka musi składać się z podzbioru znaków ASCII - alfanumerycznych, niektórych znaków interpunkcyjnych, a nie wielu innych. Po drugie, nic nie ma w definicji wartości nagłówka, która ogranicza ją do ASCII lub wyklucza znaki 8-bitowe: jest wyraźnie złożona z oktetów, z ograniczonymi tylko znakami kontrolnymi (zwróć uwagę, że CR i LF są uważane za kontrole). Ponadto komentarz do produkcji TEKSTU sugeruje, że oktety należy interpretować jako zawarte w ISO-8859-1 i że istnieje mechanizm kodowania (który, nawiasem mówiąc, jest okropny), do reprezentowania znaków poza tym kodowaniem.

Tak więc, aby odpowiedzieć w szczególności na @BalusC, jasne jest, że zgodnie ze specyfikacją wartości nagłówka są w ISO-8859-1. Wysłałem wysoko 8859-1 znaków (konkretnie niektóre akcentowane samogłoski używane w języku francuskim) w nagłówku z Tomcat i kazałem je poprawnie interpretować przez Firefox, więc do pewnego stopnia działa to zarówno w praktyce, jak i w teorii (chociaż był to nagłówek lokalizacji, który zawiera adres URL, a te znaki nie są dozwolone w adresach URL, więc było to w rzeczywistości nielegalne, ale na innej zasadzie!).

To powiedziawszy, nie będę polegał na ISO-8859-1 działającej na wszystkich serwerach, serwerach proxy i klientach, więc trzymałbym się ASCII w ramach programowania obronnego.

Tom Anderson
źródło
3
Nowsza specyfikacja HTTP RFC7230 mówi „Nowo zdefiniowane pola nagłówka POWINNY ograniczać swoje wartości pól do oktetów US-ASCII”.
Robert Tupelo-Schneck
23

RFC6648 zaleca założenie, że nagłówek niestandardowy „może stać się znormalizowany, publiczny, powszechnie wdrażany lub używany w wielu implementacjach”. Dlatego zaleca się, aby nie poprzedzać go „X-” lub podobnymi konstrukcjami.

Istnieje jednak wyjątek „gdy jest bardzo mało prawdopodobne, aby [Twój nagłówek] został kiedykolwiek znormalizowany”. W przypadku takich nagłówków „związanych z implementacją i do użytku prywatnego” RFC stwierdza, że ​​przestrzeń nazw, taka jak prefiks dostawcy, jest uzasadniona.

Edward Brey
źródło
6
„RFC6648 zaleca założenie, że niestandardowy nagłówek” może stać się znormalizowany, publiczny, powszechnie wdrażany lub użyteczny w wielu implementacjach. „Myślę, że daje to powód do używania X-prefiksu, ponieważ bardziej prawdopodobne jest, że coś bez żadnego prefiksu może zostać znormalizowane.
Konrad
@Konrad Jeśli zakładasz , że podobny nagłówek innej osoby (nie twój) może zostać znormalizowany, możesz uniknąć konfliktu X-, ale jest to inne założenie niż pierwotnie przyjmuje RFC6648. Wyjątek RFC uwzględnia potencjalne konflikty między przyszłym nagłówkiem standardowym a nagłówkiem innego dostawcy, którego technologia może zostać zintegrowana z Twoją poprzez połączenie firmy itp. Dlatego wyjątek wymaga prefiksu dostawcy.
Edward Brey
17

Modyfikowanie, lub bardziej poprawnie, dodawanie dodatkowych nagłówków HTTP jest świetnym narzędziem do debugowania kodu, jeśli nic więcej.

Gdy żądanie URL zwraca przekierowanie lub obraz, nie ma „strony” HTML, która tymczasowo zapisuje wyniki debugowania kodu - przynajmniej nie takiego, który jest widoczny w przeglądarce.

Jednym z podejść jest zapisanie danych w lokalnym pliku dziennika i przejrzenie tego pliku później. Innym jest tymczasowe dodanie nagłówków HTTP odzwierciedlających debugowane dane i zmienne.

Regularnie dodaję dodatkowe nagłówki HTTP, takie jak X-fubar-somevar: lub X-testing-someresult: w celu przetestowania rzeczy - i znalazłem wiele błędów, które w innym przypadku byłyby bardzo trudne do wyśledzenia.

g1smd
źródło
2
Dlaczego miałby używać tego „standardu”? Nagłówki działają tak samo. Nawet z prefiksem „WHO_EVER_READS_THIS_IS_DUMB_” ...
Niesamowity
16

Rejestr nazw pól nagłówka jest zdefiniowany w RFC3864 i w „X-” nie ma nic specjalnego.

O ile mi wiadomo, nie ma wytycznych dla prywatnych nagłówków; w razie wątpliwości unikaj ich. Lub spójrz na Framework Extension HTTP ( RFC 2774 ).

Byłoby interesujące zrozumieć więcej przypadków użycia; dlaczego nie można dodać informacji do treści wiadomości?

Julian Reschke
źródło
13
Głównym powodem, dla którego rozważam niektóre niestandardowe nagłówki, jest to, że mogę podejmować decyzje o routingu bez konieczności analizowania treści ...
Rozwel