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

Świetny zasób, aby wybrać poprawny kod błędu HTTP dla API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Fragment artykułu:

Od czego zacząć:

2XX / 3XX:

4XX:

5XX:

Głównym wyborem jest to, czy chcesz traktować kod statusu HTTP jako część REST API, czy nie.

W tym momencie (Sierpień, 2015) zalecam używanie kodu statusu HTTP jako części API. Teraz jest o wiele łatwiej zobaczyć kod powrotu podczas korzystania z frameworków niż w przeszłości. W szczególności teraz łatwiej jest dostrzec sprawę zwrotu Nie-200 i zbiór odpowiedzi Nie-200 niż w przeszłości.

Kod statusu HTTP jest częścią twojego api

1. Musisz starannie wybrać kody 4xx, które pasują do warunków błędu. Ty może zawierać komunikat rest, xml lub tekst zwykły jako ładunek zawierający podkod i komentarz opisowy.

2. Klienci będą musieli użyć frameworku oprogramowania, który umożliwia im uzyskanie kodu stanu na poziomie HTTP. Zazwyczaj robi-w stanie, nie zawsze prosto do przodu.

3. Klienci będą musieli odróżnić kody statusu HTTP, które wskazują na błąd komunikacji, od własnych kodów statusu, które wskazują na poziomie aplikacji problem.

Kod statusu HTTP nie jest częścią twojego api

1. Kod statusu HTTP będzie zawsze wynosił 200, jeśli Twoja aplikacja otrzymała żądanie, a następnie odpowiedziała (zarówno przypadki sukcesu, jak i błędów)

2. Wszystkie odpowiedzi powinny zawierać informacje o "kopercie" lub "nagłówku". Typowo coś w stylu:

   envelope_ver: 1.0
   status:  # use any codes you like. Reserve a code for success. 
   msg: "ok" # A human string that reflects the code. Useful for debugging.
   data: ...  # The data of the response, if any.

3. Ta metoda może być łatwiejsza dla klientów, ponieważ status odpowiedzi jest zawsze w tym samym miejscu (bez Pod-kodów potrzebne), brak ograniczeń na kodach, nie ma potrzeby pobierania kodu statusu na poziomie HTTP.

Oto post z podobnym pomysłem: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Główne zagadnienia:

1. Pamiętaj, aby dołączyć numery wersji, dzięki czemu możesz później zmienić semantykę api, jeśli zajdzie taka potrzeba.

2. Dokument...

Pamiętaj, że jest więcej kodów statusu niż te zdefiniowane w RFC HTTP/1.1, rejestr IANA znajduje się w http://www.iana.org/assignments/http-status-codes . dla sprawy, o której wspomniałeś kod statusu 507 brzmi dobrze.

Jak zauważyli inni, posiadanie encji odpowiedzi w kodzie błędu jest całkowicie dopuszczalne.

Pamiętaj, że błędy 5xx są po stronie serwera, czyli klient nie może niczego zmienić w swoim żądaniu, aby żądanie przeszło. Jeśli limit Klienta zostanie przekroczony, to zdecydowanie nie jest to błąd serwera, więc należy unikać 5xx.

Wiem, że jest to bardzo późno na imprezę, ale teraz, w roku 2013, mamy kilka rodzajów mediów, które obejmują obsługę błędów we wspólnym rozproszonym (spokojnym) stylu. Zobacz " vnd.error", application / vnd.error+json (https://github.com/blongden/vnd.error ) i "szczegóły problemu dla API HTTP", application/problem+json ( https://tools.ietf.org/html/draft-nottingham-http-problem-05).

Są dwa rodzaje błędów. Błędy aplikacji i błędy HTTP. Błędy HTTP są po to, aby twój handler AJAX wiedział, że wszystko poszło dobrze i nie powinno być używane 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 to, jak zaprojektujesz błędy aplikacji, zależy naprawdę od Ciebie. Przepełnienie stosu np. wysyła obiekt z response, data i message właściwości. Odpowiedź według mnie zawiera true lub false, aby wskazać, czy operacja zakończyła się sukcesem (zwykle w przypadku operacji zapisu). Dane zawierają ładunek (Zwykle do operacji odczytu), a wiadomość zawiera dodatkowe metadane lub przydatne komunikaty(takie jak komunikaty o błędach, gdy response jest false).

Zgoda. Podstawową filozofią REST jest korzystanie z infrastruktury internetowej. Kody statusu HTTP są frameworkiem wiadomości, który pozwala stronom komunikować się ze sobą bez zwiększania ładunku HTTP. Są one już ustalone uniwersalne kody przekazujące status odpowiedzi, a zatem, aby być naprawdę spokojny, aplikacje muszą korzystać z tych ram do komunikowania statusu odpowiedzi.

Wysłanie odpowiedzi o błędzie w kopercie HTTP 200 jest mylące i wymusza klient (konsument api) do analizy wiadomości, najprawdopodobniej w niestandardowy lub zastrzeżony sposób. Nie jest to również efektywne - zmusisz swoich klientów do analizy ładunku HTTP za każdym razem, aby zrozumieć "rzeczywisty" status odpowiedzi. Zwiększa to przetwarzanie, dodaje opóźnienia i tworzy środowisko do popełniania błędów przez Klienta.

Modelowanie api w oparciu o istniejące "najlepsze praktyki" może być dobrym rozwiązaniem. 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 błędów - czy to WYJĄTKÓW biznesowych lub innych. Gdyby użycie 2xx do jakiejkolwiek odpowiedzi było zamierzonym przypadkiem użycia w protokole, nie mieliby innych kodów statusu w pierwszej kolejności.

Nie zapomnij o błędach 5xx, a także o błędach aplikacji.

W tym przypadku co z 409 (konflikt)? Zakłada to, że użytkownik może rozwiązać problem, usuwając zapisane zasoby.

W Przeciwnym Razie 507 (nie do końca standardowe) może również działać. Nie użyłbym 200, chyba że używasz 200 do błędów w ogóle.

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