Nagłówek Sunset w API i kiedy go wysyłać

Sunset to pojedynczy nagłówek odpowiedzi, zdefiniowany w RFC 8594, który mówi wywołującemu, kiedy zasób przestanie odpowiadać. Deprecacja API opisuje pełny harmonogram ogłoszenie-przypomnienie-brownout-wycofanie i powiadomienia, które mu towarzyszą; ten tekst dotyczy jednego czytelnego dla maszyny sygnału w tym harmonogramie, tego, co naprawdę mówi, i jednego przypadku, w którym sam RFC mówi, by go nie wysyłać.

Co mówi nagłówek Sunset, a czego nie mówi?

Zawiera pojedynczą datę HTTP, moment, w którym zasób ma przestać odpowiadać:

Sunset: Sat, 31 Dec 2028 23:59:59 GMT

RFC nazywa to wskazówką, nie gwarancją: nie obiecuje, że zasób będzie działał aż do tego znacznika czasu, i nic nie mówi o tym, jak będzie wyglądać awaria później. Wywołujący mogą dostać 4xx, przekierowanie albo brak odpowiedzi w ogóle; nagłówek tego nie rozróżnia. Znacznik czasu już w przeszłości oznacza „teraz, albo w dowolnym momencie”, a nie błąd w wartości. Nic z tego nie jest wymuszane przez protokół. Klient, który nigdy nie czyta nagłówka, zachowuje się dokładnie tak jak zawsze i dowiaduje się, że zasób zniknął, w ten sam sposób, w jaki dowiedziałby się i tak.

Kiedy naprawdę powinniście go wysłać?

Dopiero gdy zasób naprawdę ma przestać odpowiadać, a nie wtedy, gdy jest tylko już niezalecanym wyborem. RFC jasno mówi, że deprecacja przebiega w dwóch etapach, a pole nagłówka Sunset należy tylko do drugiego z nich: w pierwszym etapie, czyli ogłoszeniu, że wersja nie jest już preferowana, API pozostaje w pełni sprawne i to pole nagłówka tam nie ma zastosowania. Ma zastosowanie dopiero wtedy, gdy wersja jest już faktycznie zaplanowana do przestania odpowiadania.

To odpowiada wprost harmonogramowi deprecacji: nagłówek Deprecation wychodzi od pierwszego dnia, na etapie ogłoszenia; Sunset opisuje datę, w której stare zachowanie naprawdę się skończy, czyli tę samą datę, którą czteroetapowy harmonogram nazywa wycofaniem. Wysłanie Sunset pierwszego dnia nie jest błędem, skoro data jest już wtedy ustalona, ale wysłanie go bez wcześniejszego ogłoszenia deprecacji, albo ustawienie go dla wersji, której wycofania jeszcze naprawdę nie postanowiliście, mówi wywołującym coś, czego jeszcze nie zdecydowaliście.

Czy wchodzi w interakcję z cache’owaniem?

Nie, i RFC mówi to wprost: Sunset i cache’owanie HTTP rozwiązują niepowiązane problemy i należy je czytać jako uzupełniające się, a nie nakładające. Nagłówki cache’owania mówią, kiedy bezpiecznie ponownie użyć zapisanej kopii; Sunset nic nie mówi o obecnym stanie zasobu, tylko że sam zasób przestanie istnieć. Odpowiedź może być w pełni cache’owalna aż do samego momentu wygaśnięcia. Nie używajcie jednego, by przybliżyć drugie, i nie zakładajcie, że długi max-age znosi zbliżającą się datę wygaśnięcia, ani odwrotnie.

Czy jeden nagłówek może wygasić więcej niż jeden endpoint?

Nagłówek dotyczy zasobu, który go zwrócił, ale RFC pozwala usłudze udokumentować szerszy zakres: datę Sunset na zasobie głównym API można zdefiniować tak, by oznaczała, że znika całe API, a nie tylko ten jeden URL. Haczyk polega na tym, że działa to tylko dla wywołujących, którzy już znają waszą regułę zakresu. Wywołujący, który czyta nagłówek dosłownie, widzi wygaszenie tylko jednego zasobu, o który zapytał, i nic więcej, więc szerszy zakres trzeba gdzieś spisać tak, by wywołujący mógł to znaleźć, a nie tylko domyślić się.

Co powinno iść razem z nagłówkiem?

Link do miejsca, gdzie wycofanie jest wyjaśnione. RFC 8594 rejestruje własną relację linku sunset dokładnie do tego: wskazywania zasobu, który opisuje politykę wycofania, nadchodzącą datę albo sposób migracji, osobno od gołego znacznika czasu w nagłówku.

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

Skierowanie tego linku na własne przykłady changelogów albo dedykowaną stronę migracji zamienia nagłówek, którego kod klienta prawie nikt nie sprawdza, w coś, co człowiek, który faktycznie szuka, znajdzie od razu. Połączcie to z relacją successor-version z nagłówków deprecacji a wywołujący dostanie z samej odpowiedzi zarówno to, dokąd iść, jak i co zastępuje tę wersję.

Jak to wygląda od początku do końca?

Załóżmy, że v1 znika 1 marca 2027. Ogłoszenie deprecacji pierwszego dnia dodaje Deprecation i Link: rel="successor-version" do każdej odpowiedzi v1, zgodnie z nagłówkami deprecacji, ale wstrzymuje się z Sunset, dopóki data wycofania nie jest naprawdę ustalona, a nie tylko zastępcza. Gdy już jest, każda odpowiedź v1 niesie:

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

Bramka albo monitoring wywołującego może alarmować niezależnie na podstawie każdego z nagłówków: Deprecation mówi, że istnieje nowsza wersja, Sunset mówi, że ta ma już odliczany czas. Żaden z nagłówków nie musi się zmienić przed 1 marca; zmienia się sama odpowiedź, tego dnia i podczas ewentualnych okien brownoutu zaplanowanych wcześniej.

Czy brownout zmienia treść nagłówka?

Sama wartość nagłówka nie musi się zmieniać dla zaplanowanego brownoutu: data wygaśnięcia pozostaje datą wygaśnięcia, niezależnie od tego, czy zasób wcześniej okresowo zawodzi. Zmienia się odpowiedź, nie nagłówek. Zaplanowanie krótkich okien 410 Gone w tygodniach przed ogłoszoną datą, jak opisuje Deprecacja API, to właśnie to, co zamienia pierwszy kontakt wywołującego z awarią w próbę generalną, a nie prawdziwe wydarzenie w dniu, w którym nadchodzi data z nagłówka.

FAQ

Czy jakiekolwiek prawdziwe klienty HTTP albo narzędzia naprawdę czytają nagłówek Sunset? Rzadko, po stronie klienta. Jego wartość jest głównie dla tego, kto obsługuje infrastrukturę między wami a wywołującym: bramka API albo narzędzie monitorujące, które skonfigurujecie do obserwowania nagłówka, może zaalarmować wasz własny zespół, albo zespół partnera, na długo zanim kod wywołującego cokolwiek zauważy. Traktujcie to jako sygnał, wokół którego budujecie narzędzia, a nie taki, co do którego możecie założyć, że druga strona już go ma.

Czy Sunset to to samo co Cache-Control: max-age? Nie. max-age mówi o tym, jak długo zapisana kopia pozostaje ważna; Sunset mówi o tym, kiedy zasób w ogóle przestaje istnieć. Odpowiedź może mieć krótki max-age i datę Sunset odległą o lata, albo odwrotnie, i żaden z nagłówków nie ogranicza drugiego.

Czy mogę wysłać Sunset dla pojedynczego pola, które znika, a nie dla całego endpointu? Nie, nagłówek jest przypisany do zasobu, czyli URL-a, a nie do pola wewnątrz treści odpowiedzi. Dla pola, parametru albo wartości enum, które znikają, podczas gdy sam endpoint pozostaje dostępny, użyjcie zamiast tego nagłówka Deprecation i wpisu w changelogu; Deprecacja API opisuje ogłaszanie dokładnie takiej zmiany.

Co, jeśli data wygaśnięcia musi się przesunąć? Zaktualizujcie wartość nagłówka i napiszcie o tym we wpisie changeloga, który ogłosił ją po raz pierwszy; ciche zmienianie opublikowanej daty to sposób, w jaki wywołujący dochodzi do wniosku, że żadna z waszych dat nie jest prawdziwa. RFC opisuje tę wartość jako wskazówkę właśnie dlatego, że daty czasem się przesuwają, ale przesunięta data bez wyjaśnienia kosztuje was też kolejną.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Dokumentacja dla deweloperów, Przykłady changeloga