Konwencja dotycząca nagłówka odpowiedzi HTTP w celu powiadomienia klientów o przestarzałym interfejsie API

86

Uaktualniam nasze punkty końcowe interfejsu API REST i chcę powiadomić klientów, gdy wywołują punkt końcowy, który ma być przestarzały.
Jakiego nagłówka powinienem użyć w odpowiedzi z komunikatem typu „Ta wersja interfejsu API jest przestarzała, zapoznaj się z najnowszą dokumentacją, aby zaktualizować punkty końcowe”

rest http http-status-codes deprecation-warning BlazingFrog
źródło

Odpowiedzi:

75

Nie zmieniłbym niczego w kodzie statusu, aby był kompatybilny wstecz. W odpowiedzi dodałbym nagłówek „Ostrzeżenie”:

Warning: 299 - "Deprecated API"

Możesz także określić „-” z „Agentem”, który emituje ostrzeżenie i być bardziej wyraźnym w tekście ostrzeżenia:

Warning: 299 api.blazingFrog.com "Deprecated API: use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"

Tutaj określono nagłówek ostrzeżenia: https://tools.ietf.org/html/rfc7234#section-5.5 . Kod ostrzegawczy 299 jest typowy, „Przestarzały” nie jest standardem.

Musisz powiedzieć swoim klientom API, aby rejestrowali ostrzeżenia HTTP i monitorowali je.

Do tej pory nigdy z niego nie korzystałem, ale kiedy moja firma będzie bardziej dojrzała w Rest API, zintegruję ją.

Edycja (2019-04-25): Jak wspomniał @Harry Wood, nagłówek Warning znajduje się w rozdziale dotyczącym buforowania w dokumentacji. Jednak RFC jest jasneWarnings can be used for other purposes, both cache-related and otherwise.

Jeśli wolisz alternatywną metodę, ta wersja robocza https://tools.ietf.org/html/draft-dalal-deprecation-header-00 sugeruje nowy nagłówek „Wycofanie”.

BenC
źródło
1
Data ostrzeżenia na końcu wartości-ostrzeżenia nie służy tutaj celowi i najlepiej jest ją pominąć, w przeciwnym razie można zmylić klientów: „Jeśli odbiorca. . . otrzyma datę-ostrzeżenia, która różni się od Datewartości w tej samej wiadomości, odbiorca MUSI wykluczyć wartość-ostrzeżenia. . . przed . . . używając wiadomości. ”
Vasiliy Faronov
Jeśli nie obejmują ostrzec aktualne, musi być sformatowany w taki sam sposób, jak w Datenagłówku: "Thu, 02 Apr 2015 12:25:32 GMT".
Vasiliy Faronov
@VasiliyFaronov: masz rację, ponieważ w takim przypadku (przestarzałe API) ten komunikat ostrzegawczy będzie zawsze prawdziwy w przyszłości. Jeśli więc odpowiedź (z komunikatem ostrzegawczym) jest wysyłana przez pamięć podręczną w proxy i data wiadomości jest inna, ostrzeżenie zostanie zignorowane, ale nadal będzie ważne.
Edytuję
Czy ten nagłówek „ostrzeżenia” nie jest jednak związany z buforowaniem? Mam na myśli, że w twoim odnośniku do dokumentacji wspomina się o buforowaniu, ale także, że cały dokument RFC wydaje się być związany z buforowaniem. Ale Warningnagłówek wygląda dobrze jako wolne miejsce na tekst, aby opisać wycofanie. Te Deprecationi Sunsetnagłówki wymienione w innych odpowiedzi, wydaje się być pojawiające się standardowym rozwiązaniem dla Wycofanie opisujące w sposób bardziej mocniej potencjalnie odczytu maszynowego.
Harry Wood
1
Warningnagłówek nie dotyczy tylko pamięci podręcznych. Pierwsze zdanie w Warningsekcji to „Ostrzeżenia mogą być używane do innych celów, zarówno związanych z pamięcią podręczną, jak i nie tylko”.
Çelebi Murat
37

Możesz użyć 410 (Gone) .

Oto jak opisują to definicje kodów stanu W3C :

410 (odszedł)

Żądany zasób nie jest już dostępny na serwerze i nie jest znany adres do przekazywania. Oczekuje się, że ten stan będzie trwały. Klienci z możliwością edycji linków POWINNI usuwać odniesienia do identyfikatora URI żądania po zatwierdzeniu przez użytkownika. Jeśli serwer nie wie lub nie ma możliwości określenia, czy warunek jest trwały, NALEŻY zamiast tego użyć kodu statusu 404 (Nie znaleziono). Ta odpowiedź może być buforowana, chyba że wskazano inaczej.

Odpowiedź 410 ma przede wszystkim pomóc w zadaniu utrzymania sieci WWW poprzez powiadomienie odbiorcy, że zasób jest celowo niedostępny i że właściciele serwera chcą, aby zdalne łącza do tego zasobu zostały usunięte. Takie zdarzenie jest powszechne w przypadku usług promocyjnych o ograniczonym czasie trwania i zasobów należących do osób, które już nie pracują w witrynie serwera. Nie jest konieczne oznaczanie wszystkich trwale niedostępnych zasobów jako „zaginionych” ani utrzymywanie tego oznaczenia przez dowolny okres czasu - to zależy od właściciela serwera.

Emanuil Rusev
źródło
36
Problem z 410 polega na tym, że nie spełnia on wymagania „do wycofania” ... Działa dobrze, gdy API zniknie, ale nie oznacza to , że zniknie w przyszłości .
Julien Genestoux
3
Jeśli
zwrócisz
4
410 Gonenie chodzi o wycofanie, chodzi o metodę, która już nie jest dostępna. Jak powiedział @BenC, lepszym sposobem jest użycie nagłówka Warning
sempasha
2
To może być kolejna faza przestarzałego API
Shiplu Mokaddim
16

Poszedłbym / bym poszedł z 301 (przeniesiony na stałe). Kody serii 300 mają powiedzieć klientowi, że ma działanie do wykonania.

u07ch
źródło
4
Prawdopodobnie tego użyję, gdy punkt końcowy zostanie faktycznie usunięty, ale chcę dać im szansę na otrzymanie powiadomienia przez jakiś czas (zakładając, że będą patrzeć na nagłówki HTTP w odpowiedzi), aby mogli wprowadzić niezbędne zmiany ich koniec.
BlazingFrog
2
Tak naprawdę nie ma statusu, aby się przeprowadzić. 302 (Żądany zasób znajduje się tymczasowo w innej lokalizacji, ale nadal można go znaleźć pod
żądanym
1
Nie szukam statusu, ale „standardowego” nagłówka do dodania do odpowiedzi.
BlazingFrog
1
Nie ma standardowego nagłówka dla tego rodzaju odpowiedzi. Należy utworzyć własny nagłówek i opisać go w dokumentacji własnego interfejsu API.
Brian Kelly,
Myślę, że każdy kod odpowiedzi> = 300 powinien zepsuć wszystko. 299 umożliwi klientom utrzymanie aplikacji przy życiu do czasu wyłączenia interfejsu API podczas dokonywania niezbędnych zmian.
devlord
6

Poleciłbym 207 Multi-Statusodpowiedź, wskazującą, że jest to odpowiedź pomyślna, ale potencjalnie ma ona również drugi status wycofania.

typoneerror
źródło
1
Ciekawy. Nie wiedziałem o tym, ale myślę, że w praktyce istnieje duże niebezpieczeństwo, że wprowadzisz przełomową zmianę dla niektórych klientów, zamieniając na inny kod odpowiedzi, nawet jeśli nadal mieści się w zakresie 200. Myślę, że możesz delikatnie podnieść ciśnienie. Zacznij od Deprecationnagłówka (który klienci prawdopodobnie zignorują niestety), a następnie użyj tego 207 kodu, później przeniesiono 301, a ostatecznie 410 zniknął!
Harry Wood
4

Udoskonalam odpowiedź @ dret. Istnieją dwa odpowiednie nagłówki HTTP do wycofania: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) i Sunset.

Aby poinformować użytkowników o planowanym wycofaniu, Deprecationnależy użyć nagłówka HTTP. Oznacza to, że punkt końcowy zostanie usunięty jakiś czas w przyszłości. Pozwala również wskazać datę ogłoszenia tego i opisać alternatywne zasoby.

Aby poinformować użytkowników o planowanej dacie wygaśnięcia przestarzałego zasobu, Sunsetoprócz nagłówka Deprecation należy użyć nagłówka. Jest to opisane w sekcji # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 .

Projekt nr 11 https://tools.ietf.org/html/draft-wilde-sunset-header-11 z Sunsetwyjaśnia nagłówka ten aspekt, a także w punkcie 1.4 https://tools.ietf.org/html/draft-wilde -sunset-header-11 # section-1.4 .

sdatspun2
źródło
3

Istnieje pole nagłówka HTTP o nazwie, Sunsetktóre ma sygnalizować zbliżające się wycofanie zasobu. https://tools.ietf.org/html/draft-wilde-sunset-header jest na ostatnim etapie stania się RFC. Idealnie Sunsetbyłoby, gdyby twój interfejs API udokumentował, że będzie używany , aby klienci mogli go szukać i działać na jego podstawie, jeśli chcą.

dret
źródło