Niestandardowe nagłówki HTTP: konwencje nazewnictwa

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 :)

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

...

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

4. Zalecenia dla projektantów protokołów

...

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

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

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

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

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.

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.

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.

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?