Szukam wskazówek dotyczących dobrych praktyk, jeśli chodzi o zwracanie błędów z interfejsu API REST. Pracuję nad nowym interfejsem API, dzięki czemu mogę teraz obrać dowolny kierunek. Mój typ zawartości to XML, ale planuję w przyszłości obsługiwać JSON.
Teraz dodam kilka przypadków błędów, na przykład klient próbuje dodać nowy zasób, ale przekroczył limit miejsca. Obsługuję już niektóre przypadki błędów z kodami stanu HTTP (401 dla uwierzytelnienia, 403 dla autoryzacji i 404 dla zwykłych identyfikatorów URI niepoprawnego żądania). Przejrzałem błogosławione kody błędów HTTP, ale żaden z zakresów 400–417 nie wydaje się odpowiedni do zgłaszania błędów specyficznych dla aplikacji. Na początku kusiło mnie, aby zwrócić błąd aplikacji z 200 OK i konkretnym ładunkiem XML (tj. Zapłać nam więcej, a dostaniesz potrzebną pamięć!), Ale przestałem myśleć o tym i wydaje się, że mydło (/ wzruszając ramionami). Poza tym wydaje mi się, że dzielę odpowiedzi na błędy na osobne przypadki, ponieważ niektóre są oparte na kodzie stanu HTTP, a inne na treści.
Więc jakie są zalecenia branżowe? Dobre praktyki (proszę wyjaśnić dlaczego!), A także, od klienta pow, jaki rodzaj obsługi błędów w interfejsie API REST ułatwia życie kodu klienta?
źródło
Odpowiedzi:
Nie zwróciłbym 200, chyba że naprawdę nie było nic złego w żądaniu. Z RFC2616 , 200 oznacza „żądanie się powiodło”.
Jeśli limit miejsca klienta zostanie przekroczony (z jakiegokolwiek powodu), zwrócę 403 (zabronione):
To mówi klientowi, że żądanie było OK, ale nie powiodło się (coś, czego 200 nie robi). Daje to również możliwość wyjaśnienia problemu (i jego rozwiązania) w treści odpowiedzi.
Jakie jeszcze konkretne warunki błędu miałeś na myśli?
źródło
Świetny zasób, aby wybrać prawidłowy kod błędu HTTP dla swojego interfejsu API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html
Fragment artykułu:
Gdzie zacząć:
2XX / 3XX:
4XX:
5XX:
źródło
Głównym wyborem jest to, czy chcesz traktować kod stanu HTTP jako część interfejsu API REST, czy nie.
Oba sposoby działają dobrze. Zgadzam się, ściśle mówiąc, jednym z pomysłów REST jest to, że powinieneś używać kodu statusu HTTP jako części swojego API (zwróć 200 lub 201 dla udanej operacji i 4xx lub 5xx w zależności od różnych błędów). , nie ma policji REST. Możesz robić co chcesz. Widziałem znacznie bardziej skandaliczne interfejsy API inne niż REST nazywane „RESTful”.
W tym momencie (sierpień 2015) zalecamy używanie kodu stanu HTTP jako części interfejsu API. Teraz o wiele łatwiej jest zobaczyć kod powrotu podczas korzystania z frameworków niż w przeszłości. W szczególności łatwiej jest teraz zobaczyć przypadek zwrotu innej niż 200 i treść odpowiedzi innych niż 200 niż w przeszłości.
Kod stanu HTTP jest częścią interfejsu API
Musisz starannie wybrać kody 4xx, które pasują do twoich błędów. Jako ładunek, który zawiera subkod i komentarz opisowy, możesz dołączyć wiadomość odpoczynku, XML lub zwykły tekst.
Klienci będą musieli skorzystać z frameworka oprogramowania, który umożliwi im uzyskanie kodu stanu na poziomie HTTP. Zwykle wykonalne, nie zawsze proste.
Klienci będą musieli rozróżniać kody stanu HTTP wskazujące na błąd komunikacji i własne kody stanu wskazujące na problem na poziomie aplikacji.
Kod statusu HTTP NIE jest częścią twojego interfejsu API
Kod stanu HTTP będzie zawsze wynosił 200, jeśli aplikacja otrzyma żądanie, a następnie odpowie na nie (zarówno przypadki powodzenia, jak i błędy)
WSZYSTKIE odpowiedzi powinny zawierać informacje „koperta” lub „nagłówek”. Zazwyczaj coś takiego:
Ta metoda może być łatwiejsza dla klientów, ponieważ status odpowiedzi jest zawsze w tym samym miejscu (nie są potrzebne subkody), bez ograniczeń kodów, nie trzeba pobierać kodu stanu na poziomie HTTP.
Oto post z podobnym pomysłem: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/
Główne kwestie:
Pamiętaj o podaniu numerów wersji, aby w razie potrzeby później zmienić semantykę interfejsu API.
Dokument...
źródło
Pamiętaj, że jest więcej kodów statusu niż te zdefiniowane w RFC HTTP / 1.1, rejestr IANA znajduje się na stronie http://www.iana.org/assignments/http-status-codes . W przypadku, o którym wspomniałeś, kod stanu 507 brzmi dobrze.
źródło
507
tym celem. Moją interpretacją507
jest to, że na serwerze brakuje miejsca, a nie, że na koncie brakuje miejsca.5xx
błędy dotyczą błędów związanych z serwerem.Jak zauważyli inni, istnienie jednostki odpowiedzi w kodzie błędu jest całkowicie dopuszczalne.
Pamiętaj, że błędy 5xx są po stronie serwera, czyli klient nie może nic zmienić w swoim żądaniu, aby żądanie zostało zrealizowane. Jeśli limit klienta zostanie przekroczony, to z pewnością nie jest to błąd serwera, więc należy unikać 5xx.
źródło
Istnieją dwa rodzaje błędów. Błędy aplikacji i błędy HTTP. Błędy HTTP mają po prostu poinformować program obsługi AJAX, że wszystko poszło dobrze i nie należy go używać do niczego innego.
5xx
błąd serwera2xx Sukces
Jednak sposób zaprojektowania błędów aplikacji zależy od Ciebie. Przepełnienie stosu na przykład wysyła obiekt z
response
,data
imessage
właściwości. Odpowiedź, która moim zdaniem zawieratrue
lubfalse
wskazuje, czy operacja się powiodła (zwykle w przypadku operacji zapisu). Dane zawierają ładunek (zwykle do operacji odczytu), a komunikat zawiera wszelkie dodatkowe metadane lub przydatne komunikaty (takie jak komunikaty o błędach, gdyresponse
sąfalse
).źródło
Wiem, że jest to bardzo późno na imprezę, ale teraz, w 2013 roku, mamy kilka rodzajów mediów do obsługi obsługi błędów w typowy sposób rozproszony (RESTful). Zobacz „vnd.error”, application / vnd.error + json ( https://github.com/blongden/vnd.error ) i „Szczegóły problemu dla interfejsów API HTTP”, application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).
źródło
Zgoda. Podstawową filozofią REST jest korzystanie z infrastruktury internetowej. Kody stanu HTTP to struktura przesyłania wiadomości, która umożliwia stronom komunikowanie się ze sobą bez zwiększania ładunku HTTP. Są one już ustanowione uniwersalnymi kodami przekazującymi status odpowiedzi, a zatem, aby być naprawdę RESTful, aplikacje muszą używać tej struktury do komunikowania statusu odpowiedzi.
Wysłanie odpowiedzi na błąd w kopercie HTTP 200 wprowadza w błąd i zmusza klienta (konsumenta interfejsu API) do przeanalizowania komunikatu, najprawdopodobniej w niestandardowy lub zastrzeżony sposób. To również nie jest wydajne - zmusisz swoich klientów do analizowania ładunku HTTP za każdym razem, aby zrozumieć „prawdziwy” status odpowiedzi. Zwiększa to przetwarzanie, dodaje opóźnienia i tworzy środowisko, w którym klient może popełniać błędy.
źródło
Najlepszym rozwiązaniem może być modelowanie interfejsu API na podstawie istniejących „najlepszych praktyk”. Na przykład oto, jak Twitter obsługuje kody błędów https://developer.twitter.com/en/docs/basics/response-codes
źródło
Proszę trzymać się semantyki protokołu. Użyj 2xx dla pomyślnych odpowiedzi i 4xx, 5xx dla odpowiedzi na błędy - czy to twoich wyjątków biznesowych czy innych. Gdyby użycie 2xx dla jakiejkolwiek odpowiedzi było zamierzonym przypadkiem użycia w protokole, nie miałyby przede wszystkim innych kodów stanu.
źródło
Nie zapomnij również o błędach 5xx w przypadku błędów aplikacji.
W takim przypadku co z 409 (konfliktem)? Zakłada się, że użytkownik może rozwiązać problem, usuwając przechowywane zasoby.
W przeciwnym razie może również działać 507 (nie do końca standardowy). Nie użyłbym 200, chyba że użyjesz 200 do błędów w ogóle.
źródło
Jeśli limit klienta zostanie przekroczony, oznacza to błąd serwera, unikaj w tym przypadku 5xx.
źródło