Jaki jest prawidłowy kod stanu HTTP dla: „Ta wersja tego API została wycofana”?

Mam interfejs API RESTful. Istnieją 3 wersje: v1, v2 i v3. Mam zamiar opublikować wersję 4 i postanowiliśmy przerwać wersję 1, co oznacza, że ​​wszystkie żądania http://example.com/v1/resourcezakończą się niepowodzeniem, ale wywołania http://example.com/v2/resourcebędą nadal działać.

Jaki jest właściwy sposób wskazania awarii? Rozważałem użycie 410 GONEkodu stanu, ale to wskazuje, że zasób nie jest już dostępny. Zasób najprawdopodobniej jest nadal dostępny, tylko należy go poprosić w inny sposób.

Rozważałem też ogólny 400kod statusu, ale to również wydawało się dziwne. Czy jest na to standardowa odpowiedź?

Wydaje się, że nie ma standardu.

W StackOverflow odpowiedź skłania 410 ma, ale myślę, że 301 na stałe przeniósł się bardziej odpowiednie.

Aby dokonać właściwego wyboru, musimy przyjrzeć się konkretnej sprawie. Jeśli Twoim celem jest niepowodzenie wykonywania wszystkich wywołań interfejsu API v1 bez podejmowania dalszych działań, 410 GONE działa na to. Jeśli chcesz mieć ciągłość, na przykład przekierowanie klienta do nowszej wersji interfejsu API, w której jego połączenie może się powieść, 3XX działa, ale który wybierasz? Myślę, że jeśli próbujesz zamknąć API v1, 301 PRZENIESIONY STAŁO pomaga wskazać, że lepiej niż 303 ZOBACZ INNE, ponieważ 301 sugeruje, że wszystkie przyszłe żądania powinny być wysyłane do nowego adresu URL, podczas gdy 303 nie wskazuje, czy ta sytuacja jest stały.

Polecam zaprojektowanie interfejsu API w taki sposób, aby każda wersja pozostała kompatybilna wstecz, aby 301 PRZENIESIONY TRWAŁO utrzymywałby interfejs API w sposób aktualny i aktualny za każdym razem, gdy dodasz nowe punkty końcowe dla nowych wersji interfejsu API. Myślę, że i tak próbujesz to zrobić.

Kody stanu HTTP

Kod stanu HTTP 302 był pierwotnie zbyt szeroki i dlatego został nieprawidłowo zaimplementowany / użyty, dlatego 303 i 307 zostały wykonane, aby rozróżnić przypadek podwójnego zastosowania 302. Niektóre interfejsy API używają 303 do innych celów.

301 PRZENIESIONY STAŁO - Kod stanu 301 (Przeniesiony na stałe) wskazuje, że do zasobu docelowego został przypisany nowy stały identyfikator URI i wszelkie przyszłe odwołania do tego zasobu powinny wykorzystywać jeden z dołączonych identyfikatorów URI.

302 ZNALEZIONO - Kod stanu 302 (Znaleziono) wskazuje, że zasób docelowy znajduje się tymczasowo pod innym identyfikatorem URI. Ponieważ przekierowanie może być czasami zmieniane, klient powinien nadal używać efektywnego identyfikatora URI żądania do przyszłych żądań.

303 ZOBACZ INNE - Odpowiedź 303 na żądanie GET wskazuje, że serwer źródłowy nie ma reprezentacji zasobu docelowego, który może być przesłany przez serwer przez HTTP. Jednak wartość pola Lokalizacja odnosi się do zasobu opisowego zasobu docelowego, tak że wysłanie żądania pobierania do tego innego zasobu może spowodować reprezentację przydatną dla odbiorców bez sugerowania, że ​​reprezentuje oryginalny zasób docelowy.

410 GONE - Kod statusu 410 (Gone) wskazuje, że dostęp do zasobu docelowego nie jest już dostępny na serwerze źródłowym i że ten stan prawdopodobnie będzie trwały. Jeśli serwer pochodzenia nie wie lub nie ma możliwości ustalenia, czy warunek jest trwały, należy zamiast niego użyć kodu stanu 404 (Nie znaleziono).

Jak radzą sobie z tym istniejące interfejsy API?

Może możesz pobrać stronę z interfejsu Google Youtube :

Gdy żądanie API nie powiedzie się, YouTube zwróci kod odpowiedzi HTTP 4xx lub 5xx, który ogólnie identyfikuje awarię, a także odpowiedź XML, która zawiera bardziej szczegółowe informacje o błędach, które spowodowały awarię. Dla każdego błędu odpowiedź XML zawiera element domeny, element kodu i ewentualnie element lokalizacji.

• BigCommerce API używa 302 FOUND.
• Wytyczne Atlassian REST API podają wskazówki na 301 PRZENIESIONO STAŁO wraz z subkodem, który szczegółowo opisuje błąd. Jest to podobne do podejścia API Youtube.

Dalsza lektura:

• Jak są wersjonowane interfejsy API REST?
• Projekt interfejsu Netflix API: kiedy przełamać trend

Przekierowania świetnie nadają się do przeniesionych zasobów. Zamiast stałego przekierowania 301 (co oznaczałoby zmianę nazwy bez zmian interfejsu API), użyłbym przekierowania 303 „Zobacz inne”.

Chcesz nadal obsługiwać starszą wersję bez przekierowań? Nawet jeśli nadal go wspierasz, a głęboko w dalszym ciągu jest on wdrażany, 501 wydaje się być w parze z twoją sytuacją. Znawcy mogliby go nadal używać, podczas gdy losowi zobaczyliby 501 dla v1.

10.5.2 501 Nie zaimplementowano

Serwer nie obsługuje funkcji wymaganych do spełnienia żądania. Jest to odpowiednia odpowiedź, gdy serwer nie rozpoznaje metody żądania i nie jest w stanie obsłużyć jej dla żadnego zasobu.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Chciałbym użyć 503 z komunikatem, że usługa jest niedostępna i wskazać na użycie nowszej wersji. Ta wiadomość może zostać zwrócona dla 50% połączeń i z czasem stopniowo wzrasta do 100%.

Dla przejrzystej migracji użyłbym 308 - Trwałe przekierowanie, ponieważ ta metoda nie modyfikuje czasownika (POST będzie POST) w przeciwieństwie do 301.