Projektuję interfejs API REST dla projektu, w którym użytkownicy są zawsze w jednym z kilku „planów” - każdy plan określa pewne ograniczenia zasobów, takie jak maksymalna liczba użytkowników, których może mieć konto lub maksymalna liczba danych, które mogą przesłać. Po osiągnięciu jednego z tych limitów użytkownicy mogą zaktualizować swoje plany (zasadniczo zapłacić), aby uzyskać więcej zasobów.
Chcę zwrócić specjalny kod stanu wskazujący sytuację, w której działanie nie może zostać wykonane z powodu limitów zasobów konta, a aktualizacja planu rozwiąże ten problem - na przykład jeśli użytkownik zużyje 100% pojemności pamięci i spróbuje przesłać dodatkowy plik otrzymają tę odpowiedź.
Kandydatami są IMHO:
403 Forbidden
- chciałbym jednak odróżnić ten przypadek od innych przypadków, w których użytkownik po prostu nie ma pozwolenia na wykonanie tej czynności.401 Unauthorized
- niezbyt dobry pomysł, używamy tego do problemów związanych z uwierzytelnianiem.402 Payment Required
- ma to sens, ale martwię się o użycie niestandardowego, ale zarezerwowanego kodu statusuCoś jeszcze mniej standardowego,
423 Locked
ponieważ jest mało prawdopodobne, że będziemy go używać do wszystkiego innego w przyszłości
Inną opcją jest użycie czegoś bardzo standardowego, na przykład 403
wskazanie specyfiki błędu w treści odpowiedzi.
Zastanawiam się, które podejście według ciebie (a) będzie działało najlepiej na dłuższą metę, a (b) lepiej przestrzega zasad RESTful.
źródło
Odpowiedzi:
Myślę, że 403 jest jedyną rozsądną odpowiedzią, chociaż metoda 405 Niedozwolona lub 409 Konflikt może być akceptowalny, nie sądzę, aby obie były tak dobre jak 403, co stanowi:
Jeśli zwrócisz błąd 403, będzie zawierać informacje o tym, dlaczego odmówiono dostępu do zasobu - niepoprawne uprawnienie jest tylko najczęstszym przypadkiem, przekroczenie limitów nie różni się znacząco - nie masz pozwolenia, ponieważ limit został przekroczony.
źródło
Uważam, że 403 jest błędne, ponieważ 403 dotyczy sytuacji, w których nie uzyskujesz dostępu do zasobu i nie ma możliwości uzyskania dostępu. Dla klientów istnieje oczywiście sposób na uzyskanie dostępu: Zapłać.
401 jest naprawdę błędny, ponieważ nie tylko używasz go do uwierzytelniania, ale po to jest.
Ponieważ piszesz interfejs API, zakładam, że ktoś inny będzie musiał napisać kod korzystający z interfejsu API i ta osoba musi przeczytać specyfikację interfejsu API. Możesz wybrać 429 „Zbyt wiele żądań”. Zwykle jest przeznaczony do ograniczania stawek (gdzie klient może na przykład składać 100 żądań dziennie), ale ma uzasadnione zastosowanie do twojej sytuacji. Myślę, że 402 (wymagana płatność) również byłaby do przyjęcia. Zależy od tego, jakich narzędzi oczekujesz od użytkowników do korzystania z interfejsu API. 429 ma ryzyko, że sprytne narzędzie spróbuje wysłać mniej żądań na minutę / godzinę / dzień i nigdy się nie uda.
BTW zgodnie z https://tools.ietf.org/html/rfc6585 błąd 429 powinien również zawierać komunikat HTML opisujący naturę problemu, więc istnieje duża szansa, że użytkownik zostanie poinformowany o problemie, jeśli podasz te informacje w twojej odpowiedzi.
źródło
402
jest opcją, ale wolę rezerwować429
na rzeczywiste cele ograniczania stawek, które prawdopodobnie dodamy w przyszłości403
ale lubię429
znacznie lepiej. Widziałem niektóre niestandardowe implementacje klientów HTTP, które zrobiły dziwne rzeczy401
i403
(na przykład strona internetowa wylogowałaby użytkownika, gdyby kiedykolwiek uzyskał 401 lub 403 z interfejsu API).WebDAV używa do tego niewystarczającej ilości pamięci HTTP 507 i zawiera dodatkowy kod błędu przekroczenia limitu w treści żądania, aby odróżnić go od innych ograniczeń przechowywania.
źródło