Czy interfejs API HTTP powinien zawsze zwracać treść?

Czy istnieje jakiś standard dotyczący odpowiedzi API HTTP?

Po przeczytaniu tego wątku dyskursu zacząłem się zastanawiać. W mojej pracy opracowujemy nasz publiczny interfejs HTTP JSON API i nie zwracamy niczego, gdy nie jest to absolutnie potrzebne (na przykład PUT do / resource / {id} zwraca tylko 200, gdy OK lub odpowiedni kod 4XX lub 5XX, ale nie JSON body)

Czy powinniśmy zwrócić rodzajowy, {"success":true}taki jak omawiany na powyższym linku, czy też jest w porządku, aby zwrócić „puste” ciało i obsłużyć wszystko kodami odpowiedzi HTTP?

Odnośnie PUT, ale dotyczy również POST. Specyfikacji HTTP odcinek 9 jest trochę pusty sprawie zasad lub nawet wszystkie (powinno), jeśli chodzi o scenariusz, który opisujesz. Wiersz odnoszący się do twojego pytania jest najbardziej objęty:

Jeśli zostanie utworzony nowy zasób, serwer źródłowy MUSI poinformować klienta użytkownika za pomocą odpowiedzi 201 (Utworzono). Jeśli istniejący zasób zostanie zmodyfikowany, MUSI zostać wysłany kod odpowiedzi 200 (OK) lub 204 (Brak treści), aby wskazać pomyślne zakończenie żądania.

Nie sądzę, żebym przez to stracił sen, ale zapytałbym, co zyskujesz, dodając do odpowiedzi fragment JSON? Właśnie przesłałeś (OK, przesyłka zbiorcza może być przesadą!), Odpowiedź powtarzająca mniej dokładnie to, co kod stanu powinien już ci powiedzieć. Jeśli twój PUT spowodował nowy zwrot obiektu 201 (zgodnie z intencją PUT), jeśli zaktualizował zwracany obiekt 204.

Nawiasem mówiąc, API na bok, zamiast 200, jeśli nic nie zwrócisz, użyj 204.

Zakładając, że opracowujesz zestaw interfejsów RESTful, nie ma standardu jako takiego, więc cokolwiek zrobisz, dobrze go udokumentuj, podaj przykłady i wszystko będzie dobrze.

Podstawowy standard HTTP nie wymaga, aby dokument został zwrócony z odpowiedzią. Ze względów ekonomicznych, gdy status HTTP przekazuje wszystko, co jest wymagane, ciało byłoby marnotrawstwem. Istnieją jednak standardy oparte na HTTP, które dodają nowe reguły.

Istnieje otwarty standard JSON API, który określa:

• Obiekt JSON MUSI znajdować się w katalogu głównym każdego dokumentu odpowiedzi API JSON . (kursywą oznacza to, co dodałem w celu wyjaśnienia tekstu)

Niestety standard nie określa sposobu reprezentowania pustego dokumentu i jest w toku. W najlepszym razie użyłbym tego jako wskazówki.

Niektóre aplikacje (takie jak ElasticSearch ) zapewniają pełny interfejs API JSON i zawsze zawierają pewne metadane, dzięki czemu można lepiej zrozumieć, w jaki sposób serwer zarządza danymi. Standardowy obiekt odpowiedzi informuje o kondycji indeksu, jeśli żądanie spowodowało błąd, liczbę dotkniętych węzłów itp. ElasticSearch używa „application / json” dla typu MIME, więc jest mało prawdopodobne, że stosują wytyczne w standard jsonapi.org.

JQuery i podobne frameworki JavaScript zakładają, że zawsze będzie dokument. Pytanie brzmi, ile kontroli błędów chcesz narzucić swoim użytkownikom interfejsu API? Jeśli zaproponujesz standardowy format dla wszystkich odpowiedzi, który jest rozszerzony tylko w zależności od rodzaju żądania, zaspokoisz potrzebę dokumentu zwrotnego i możesz ułatwić debugowanie użytkownikom interfejsu API.

Nie, na przykład, w przypadku 204 odpowiedzi nie możemy zawierać treści wiadomości. {sukces | status | isSuccessful: true} jest zbędny.

W praktyce (lub powinienem powiedzieć w późniejszej wersji jquery) pusta odpowiedź dla typu zawartości aplikacji / json powoduje błąd. Rozumiem trochę argument, że ponieważ jest to aplikacja / json, musi mieć poprawną treść json. Tak więc pusta odpowiedź dla typu zawartości aplikacji / json byłaby „null” lub „{}”, które są prawidłowym jsonem.

Jest inny sposób, który powinien działać dla jquery, czyli nie zwracanie aplikacji / json dla pustych odpowiedzi. Wystarczy użyć tekstu / zwykłego lub czegoś innego i upewnij się, że klient obsługuje ten typ.

Uwaga : Pamiętam tylko 204 za jawne zabranianie zwracania treści wiadomości. Odkryliśmy, że nie zawsze możemy użyć 204. Problemem jest nagłówek odpowiedzi upuszczenia MSIE dla 204 odpowiedzi, więc nie ma treści i nagłówków, co jest złe. Ponieważ wielu używa MSIE, musieliśmy zmienić go na 200.

Nie, ale pomoże to zachować spójność kodu. Jest również dobry do celów debugowania. Pomoże to również w utrzymaniu strony internetowej. Pamiętaj: kod błędu dotyczy komputera, komunikat o błędzie dotyczy człowieka. Sugeruję więc, abyś użył odpowiedzi. W każdym razie jego negatywny wpływ jest minimalny (zaledwie kilka bajtów wysłanych przez sieć) w porównaniu z jego zaletami. Inną rzeczą będzie uniknięcie zapominania o napisaniu treści wiadomości, gdy jest ona potrzebna.

W odpowiedzi nie zwróciłbym po prostu statusu sukcesu, kod błędu http tylko sygnalizuje sukces lub błąd. Chciałbym tylko użyć samej odpowiedzi, aby dodać szczegółowe informacje o błędach, takie jak kody błędów aplikacji lub komunikaty o błędach.

W przypadku żądań PUT, PATCH i POST zwykle zwracany jest stan, zwracany jest stan zasobu po zastosowaniu żądania, a nie pusta odpowiedź.

Dla żądań POST, które reprezentują akcję zamiast po prostu tworzenia zasobu (niezbyt RESTful, ale wciąż przydatny w praktyce), który nie ma przydatnych danych do zwrócenia, zwróciłbym odpowiedź składającą się z pustego obiektu json, tj {}. W ten sposób klient otrzymuje prawidłową odpowiedź, a dodanie niektórych informacji później nie jest w stanie jej złamać.

W przypadku żądań DELETE zwracających 204, a puste ciało jest dość powszechne, co ma sens, ponieważ zasób nie istnieje później.

Proponuję zwrócić tylko to, co jest potrzebne + trochę wyjaśnienia.

Na przykład, w zależności od tego, w jaki sposób ma być używany interfejs API, możesz dołączyć kopię obiektu istniejącą po zapisaniu.

Zatem POST z {klucz: 123} może zwrócić {klucz: 123, foo: 'bar'}.

Podstawową ideą jest to, że lepiej jest zwrócić obiekt, niż trzeba go ponownie zapytać.

To powiedziawszy, twoi klienci API nie potrzebują obiektu, nie ma potrzeby go zwracać.

Zwykle zwracam {sukces: prawda} lub coś takiego, gdy nie jest wymagany żaden obiekt na POST PUT i PATCH, ponieważ ułatwia to odbiorcy koniec. To powiedziawszy, lepiej w 99% przypadków zwrócić zapisaną reprezentację obiektu, rzadko kiedy i tak nie będzie go potrzebować, a „tańsze” jest przesłanie go w jednym żądaniu niż w dwóch.

Mówiąc konkretnie, w laboratorium doskonale sprawdza się obsługa wszystkiego za pomocą tylko kodów statusu, w prawdziwym świecie znacznie lepiej jest zwrócić niektóre dane, nawet jeśli są zbędne, aby użytkownicy interfejsu API mogli łatwo zrozumieć, co próbujesz powiedzieć.

Zwrócenie 200 {sukces: prawda} pozwala ludziom pisać kod na dwa sposoby:

if response.code == 200
  do stuff
end

i

if response.body.success
  do stuff
end

ponadto nie jest to trudne po twojej stronie.

Na koniec (przepraszam za strukturę odpowiedzi kupy), udostępniając publiczny interfejs JSON, rezygnując z dużej kontroli nad tym, jak zostanie użyty. Niektórzy klienci mogą reagować inaczej na różne podmioty (lub ich brak) lub kody statusu.