Błąd interfejsu API REST zwraca dobre praktyki [zamknięte]

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?

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).

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):

Serwer zrozumiał żądanie, ale odmawia jego spełnienia. Autoryzacja nie pomoże, a prośba NIE POWINNA zostać powtórzona. Jeśli metoda żądania nie była HEAD, a serwer chce podać do publicznej wiadomości, dlaczego żądanie nie zostało spełnione, POWINIEN opisać przyczynę odmowy w jednostce. Jeśli serwer nie chce udostępnić tych informacji klientowi, zamiast tego można użyć kodu stanu 404 (Nie znaleziono).

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?

Ś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:

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

1. 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.

2. Klienci będą musieli skorzystać z frameworka oprogramowania, który umożliwi im uzyskanie kodu stanu na poziomie HTTP. Zwykle wykonalne, nie zawsze proste.

3. 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

1. 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)

2. WSZYSTKIE odpowiedzi powinny zawierać informacje „koperta” lub „nagłówek”. Zazwyczaj coś takiego:

   koperta_wer: 1.0
   status: # użyj dowolnych kodów. Zarezerwuj kod do sukcesu.
   msg: "ok" # Ludzki ciąg znaków, który odzwierciedla kod. Przydatne do debugowania.
   data: ... # Dane odpowiedzi, jeśli istnieją.

3. 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:

1. Pamiętaj o podaniu numerów wersji, aby w razie potrzeby później zmienić semantykę interfejsu API.

2. Dokument...

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.

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.

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 serwera

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Sukces

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Jednak sposób zaprojektowania błędów aplikacji zależy od Ciebie. Przepełnienie stosu na przykład wysyła obiekt z response, datai messagewłaściwości. Odpowiedź, która moim zdaniem zawiera truelub falsewskazuje, 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, gdy responsesą false).

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 ).

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.

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

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.

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.

Jeśli limit klienta zostanie przekroczony, oznacza to błąd serwera, unikaj w tym przypadku 5xx.