Opiszę przykład:
Zaczynam tworzyć API dla piekarni. Interfejs API pozwoli użytkownikom przeszukiwać katalog w poszukiwaniu produktów do pieczenia, takich jak domowe domowe ciasteczka z miętowymi kawałkami czekolady api.examplebakery.com/search?q=.....
.
Ktoś używa tego, aby wyszukać produkt o nazwie pineapple-banana flavoured cookies
i oczywiście nie znajdzie żadnych wyników.
Czy należy to zwrócić jako błąd? Wyszukiwanie nie zakończyło się niepowodzeniem, interfejs API przeszukał i pomyślnie stwierdził, że nie można znaleźć plików cookie. Interfejs API nie powinien zwrócić 404
, ponieważ interfejs API został rzeczywiście znaleziony.
rest
http-response
Berry M.
źródło
źródło
Odpowiedzi:
Gdy są wyniki, wynikiem jest lista (JSON, na podstawie twojego komentarza). W przypadku zapytań bez wyników dane wyjściowe powinny być dokładnie takie same. Lista prosta zawiera 0 pozycji.
Więc jeśli twoja odpowiedź brzmi zwykle:
Następnie dla zapytania z 0 wynikami powinno być to:
Jeśli dołączysz również metadane dotyczące liczby „stron” wyników, linki do tych „stron” itp., Sugeruję, aby powiedzieć, że istnieje 1 „strona”.
Status HTTP powinien być taki sam, jak w przypadku wyników -
200 OK
.204 No Content
może również wydawać się opcją, ale nie dlatego, że w rzeczywistości zwracasz „treść” - pustą listę. Jeśli uważasz, że pusta lista nie liczy się jako „treść”, co jeśli zmienisz odpowiedź, aby zaoferować sugestie dotyczące pisowni? Trzon odpowiedzi nadal będzie pustą listą, ale teraz jest jeszcze więcej „treści”.Aby uzyskać bardziej przydatne informacje o kodach stanu HTTP, jpmc26 warto przeczytać ich odpowiedź .
źródło
Przy podejmowaniu decyzji o kodzie HTTP należy zawsze zadać następujące pytanie:
Zawsze decyduj, w którym zakresie powinien znajdować się kod odpowiedzi. Takie działanie szybko eliminuje wiele kodów odpowiedzi jako opcji i (co ważniejsze) znacznie ułatwia przestrzeganie semantyki kodów. Zobacz początkowe sekcje dokumentacji kodu HTTP, aby uzyskać wyjaśnienia dotyczące tego, co reprezentuje każda kategoria kodów.
W takim przypadku klient poprosił o listę wyników z filtrem z ważnego, istniejącego punktu końcowego i ma uprawnienia do uzyskania do niego dostępu. Serwer był w stanie przetworzyć żądanie i określić odpowiednie dane do zwrócenia (brak elementów), więc żądanie zakończyło się powodzeniem. Zdarza się, że filtr, który podali, odfiltrowuje wszystkie wyniki. Serwer nie powinien określać, czy tego właśnie chciał klient, czy nie, ponieważ może to być oczekiwany wynik dla niektórych klientów. Jeśli jest to w jakiś sposób problem z kodem klienta, to do obowiązków klienta należy określenie, sprawdzenie i odpowiednia obsługa. Więc to wyraźnie 2xx.
Teraz pytanie brzmi: „Które 2xx?” Zależy to od tego, jak zamierzasz odpowiedzieć na serwer.
Pozostałe nie mają zastosowania:
Powinien więc wynosić 200 lub 204, a 200 częściej prowadzi do prostszego, bardziej niezawodnego kodu klienta (szczególnie jeśli używasz spójnej struktury odpowiedzi zawierającej pustą listę).
źródło
null
tam, gdzie zwykle jest lista), nie będziesz czerpać korzyści z spójności nawet przy 200. Jednak to, co opisuję, to użycie odpowiedź, która jest zgodna z normalną strukturą i ma pustą listę, do której zwykle trafia lista wyników. 204 odbiera każdą okazję do uzyskania tak konsekwentnej odpowiedzi. Ponadto nawet w bibliotekach klienta HTTP, które mają dla niego funkcje wygody, często (zwykle?) Musisz wykonać jawne wywołanie w celu przeanalizowania JSON.Nie. Użycie 404 do wskazania „Twoje zapytanie zostało przetworzone, ale nie znaleziono żadnych dopasowań” jest okropne, ponieważ:
przepływ warunkowy oparty na obsłudze wyjątków (tj. zmuszanie do uzyskania wyjątkowego wyniku w celu utworzenia i obsługi wyjątku w kliencie, który może nie być wydajny i niewygodny)
nie znaleziono niejednoznaczności między „prawdziwą” stroną, wpisano błędne punkty końcowe
Należy pamiętać, że zawsze jest klient, który dokonuje deserializacji wiadomości i to, co klient zwraca, jest ważne; nie serializacja.
Jeśli klient powinien zwrócić null, użyj serializacji null. Jeśli klient zwróci pustą tablicę, użyj [], jeśli klient zgłosi błąd, użyj 500 i przekaż komunikat o błędzie
źródło
Bardzo dobra odpowiedź Beyond @ Ewan:
Jeśli zapytanie jest rodzajem, który zwraca zestaw wyników, wówczas pusty zestaw jest logicznie tak samo odpowiedni jak zestaw jednego lub zestawu więcej. Mówiąc ogólnie, z powodów, które stwierdza @Ewan, zmiana pustego zestawu na błąd jest bardziej szkodliwa niż pożyteczna i jest po prostu niepotrzebna.
Jeśli zapytanie jest rodzajem, który wyszukuje i zwraca określony singleton (który ma zostać znaleziony, np. Dokładne dopasowanie według identyfikatora), wówczas nie można znaleźć logicznie odpowiedniej możliwej odpowiedzi.
źródło
Zakładasz, że kod musi podjąć specjalne działanie, gdy nie zostaną zwrócone dane, ale może nie być tak. Kod może po prostu szukać liczby produktów lub dołączać wyniki do listy lub dowolnej liczby rzeczy. Powinieneś dawać użytkownikowi „błąd” tylko wtedy, gdy rzeczywiście wystąpił błąd.
źródło
Gdy korzystam z interfejsu API, jako klient muszę obsługiwać przypadki „sukcesu” inne niż przypadki „błędu”; Nie mam tam wyboru. Dlatego powinieneś zwrócić błąd w sytuacjach, które klient chce traktować inaczej, i powodzenia w sytuacjach, które klient chce traktować tak samo.
Jeśli wykonam zapytanie, które teoretycznie może zwrócić dowolną liczbę wyników, zero, jeden, dwieście i tak dalej, powinieneś zwrócić „sukces”, ilekroć API dostarcza pełną listę wszystkich wyników. I być może w przypadkach, gdy istnieje wiele wyników, zwrócono częściową listę wyników, aby uniknąć nadmiernego rozmiaru, i istnieje uzgodniony sposób, w jaki mógłbym uzyskać inne wyniki. Jest tak, ponieważ jako klient często chcę obsługiwać przypadek zerowych wyników, tak jak przypadek większej liczby wyników. Mogę potraktować to inaczej, ale nie chcę być do tego zmuszany.
Inaczej jest w przypadku, gdy szukam wartości. Oczekuję dokładnie jednego wyniku, wartości, której szukam. Potrzebuję tego jednego rezultatu, aby kontynuować to, co chcę robić w znaczący sposób. Tutaj o wiele bardziej dopuszczalne jest zwrócenie statusu 404 dla przypadku, w którym nie ma żadnej wartości, ponieważ i tak muszę inaczej traktować tę sprawę.
Podsumowanie: Jeśli klient oczekuje dowolnej liczby wyników, od zera do dużych liczb, zwróć „sukces”, jeśli wszystkie wyniki zostaną dostarczone, nawet jeśli liczba jest równa zero. Jeśli klient oczekuje dokładnie jednego wyniku, zwróć sukces, jeśli wynik zostanie znaleziony, i błąd, jeśli wynik nie zostanie znaleziony.
źródło