W jaki sposób należy obsługiwać wyjątki w RESTful API w celu uzyskania wyników zbierania?

Question

Projektujemy API RESTful do zwracania kolekcji dokumentów. Nasza początkowa implementacja używa kodów statusu HTTP do wskazania, czy żądanie nie może zostać spełnione. To wydaje się być powszechnie akceptowaną najlepszą praktyką (patrz na przykład here).

Niedawno wystąpił problem polegający na pobraniu przez użytkownika 1000 dokumentów. Nie udało się pobrać jednego z plików, dlatego zwróciliśmy kod statusu HTTP 500.

Alternatywą może być zwrócenie kodu statusu HTTP 200 z ładunkiem zawierającym 999 dokumentów, które udało nam się odzyskać, a następnie kolekcja błędów wskazująca błąd, który się nie powiódł.

Czy to alternatywne podejście jest naruszeniem restrykcyjnych zasad? W jaki sposób należy zająć się tą sytuacją? Czy są jakieś opcje poza tymi dwoma podejściami?

Answer 1

Tak, myślę, że jest to całkowicie dopuszczalne, o ile dokumentujesz, że dane, które wracasz, mogą zawierać kolekcję "błędów". Oznacza to, że niezależnie od rodzaju semantycznego nośnika, którego używasz do opisania tego zbioru dokumentów, powinna istnieć dokumentacja opisująca, jak powinna wyglądać kolekcja dokumentów i jak powinna wyglądać kolekcja błędów. Klient może następnie zdecydować, co zrobić z tymi informacjami.

Na przykład, jeśli jesteś powrocie to jako JSON (tylko przykład), może mieć taki rodzaj materiału podobnego application/json+documents lub coś, co mogłoby wyglądać tak:

{ data : { 
    documents: [ ... ], //document objects 
    errors: [ ... ] //error objects 
} 

Będziesz wtedy mieć dokumentację opisuje, jak wyglądają dokumenty i jak wyglądają błędy. W prawdziwie RESTful API są to typy multimediów, które są udokumentowane, a nie wywołania, ponieważ w prawdziwie RESTful API istnieje tylko jeden punkt końcowy, a wszystko inne jest "odkrywane" przez ten początkowy punkt końcowy, w połączeniu z semantycznymi typami mediów. Tak długo, jak dokumentujesz, że błędy są możliwe, i opisujesz format, w którym błędy będą dostarczane, powinieneś być w porządku.

Nie jest to również stan "wyjątkowy", ponieważ wydaje się, że w twoim przypadku można przewidzieć, że klient nie będzie w stanie odzyskać wszystkich dokumentów. Dlatego dobrze jest poinformować klienta o tym fakcie.

Answer 2

Istnieje linia, którą czasami trzeba przekroczyć w wyjątkowej sytuacji: dotyczy użytkownika.

Nie jest nierozsądnym powiadomienie użytkownika, że ​​ładunek jest zbyt duży i zwrócenie wewnętrznego błędu serwera.