:::: MENU ::::
Aug 10, 2017    |       2 comments

Wybór odpowiedniego kodu odpowiedzi HTTP – przestań utrudniać sobie życie!

Poniższy tekst jest mniej lub bardziej udanym tłumaczeniem artykułu Choosing an HTTP Status Code — Stop Making It Hard :).

Nie ma rzeczy prostszej niż zwrócenie kodu odpowiedzi HTTP. Strona się wyświetliła? Świetnie, zwróćmy kod 200. Strona nie istnieje? To kod 404. Przekierowujemy użytkownika na inną stronę? No to 302 albo 301.

Życie jest piękne dopóki ktoś powie Ci, że nie używasz REST-a. Nie możesz w nocy spać, bo zastanawiasz się, czy Twoja aplikacja zwraca zgodny z REST-em i zatwierdzony przez Roya Fieldinga kod odpowiedzi. Czy wystarczy 200? Czy powinien to być raczej 204 No Content? Nie, na pewno to powinien być 202 Accepted… a może jednak 201 Created?

To co komplikuje nam sytuację, to oficjalny standard HTTP/1.1, RFC, które pierwotnie powstało w 1997 roku (nie zawracaj sobie głowy RFC 2616, ani tym bardziej RFC 2068, zobacz RFC 7231). 1997 to rok, kiedy zacząłem przeglądać internet na Netscape Navigator i swoim modemie 33,6 kbps. To trochę jak używać Sztuki wojennej Sun Zi do współczesne strategii biznesowej. Nieśmiertelne rady, ale nie wyobrażam sobie jak wykorzystać pięć sposobów walki ogniem do testowania rynku.

Gdyby tylko istniał jakiś wizualny sposób na wybranie tylko tych istotnych kodów?

Proszę bardzo, internecie. Ten dzień nadszedł!

Gdzie zacząć

Może to się wydawać oczywiste, ale widziałem wielu zagubionych programistów zastanawiających się “Czy to raczej 503 Sevice Unavailable czy może bardziej 404 Not Found“? Koniec z takim podejściem. Jeżeli zastanawiasz się nad wyborem z dwóch kompletnie różnych kategorii, robisz to źle. Wróć do powyższego diagramu i zacznij jeszcze raz.

Kilka wskazówek przydatnych przy analizowaniu poszczególnych diagramów:

  • nie trzeba wierzyć mi na słowo – można odwołać się do RFC 7231 i httpstatuses.com,
  • wpis jest przeznaczony przede wszystkim dla programistów tworzący REST-owe API, co oznacza pobieżne potraktowanie kodów odpowiedzi używanych przy implementacji własnego web serwera i całkowite pominięcie kodów odpowiedzi dla serwerów proxy,
  • kody odpowiedzi pogrupowane są w trzech kategoriach:

 

 

 

 

 

I na koniec małe zastrzeżenie. Nie mam żadnych kwalifikacji, aby wypowiadać się w tej materii poza tym, że przeczytałem kilka RFC i pracuję w biurze (Racksburg), gdzie na codzień staramy się tworzyć użyteczne API. Jeżeli uważasz, że się mylę, albo że pominąłem Twój ulubiony kod, to pewnie dlatego, że jestem idiotą i powinieneś mi dać o tym znać.

2xx/3xx

4xx

5xx

Podsumowanie: Dlaczego kody odpowiedzi mają znaczenie

Nie jestem do końca przekonany czy mają.

W Facebooku jest mnóstwo mądrych ludzi, którzy stworzyli Graph API, które zwraca tylko kod 200.

Głównym argumentem pojawiającej się w dyskusji na temat zwracania różnych, mocno określonych kodów jest to, że istniejący zbiór kodów odpowiedzi jest zbyt ogólny dla współczesnych aplikacji/API. Bardzo często odpowiedź zawiera szczegóły w formacie specyficznym dla danej aplikacji (na przykład, które pola nie przeszły walidacji), aby klient mógł ją sensownie przetworzyć. Po co, w takim razie, tracić czas na dodatkową, redundantną informację w postaci kodu odpowiedzi?

Kiedy rozważamy istotność używania stosownych kodów, zdrowy rozsądek podpowiada, że protokół HTTP jest systemem składającym się z warstw i każde proxy, cache czy inna biblioteka HTTP znajdująca się między klientem i serwerem będzie działała lepiej, jeżeli kod odpowiedzi będzie miał jakieś znaczenie. Ten argument nie wydaje się być w pełni przekonujący, szczególnie biorąc pod uwagę trend serwowania aplikacji poprzez protokół HTTPS, gdzie nie można używać żadnych elementów typu proxy czy cache, które nie są zarządzanie przez główny serwer.

Zamiast tego dam Ci trzy powody, dla których uważam, że zwrócenie odpowiedniego kodu odpowiedzi ma znaczenie:

  1. Klienci już obsługują (lub niewielki kosztem mogą obsługiwać) różne kody odpowiedzi w specjalny sposób:
    • 301 Moved Permanently vs 302 Found – wpływa na SEO i Google (i inne wyszukiwarki) w inny sposób obsługują wyniki wyszukiwania dla zasobów zwracających takie statusy,
    • 301 Moved Permanently jest z założenia cachowane, podczas gdy 429 Too Many Requests z założenia nie podlega cachowaniu,
    • biblioteka kliencka po otrzymaniu 429 Too Many Requests może wstrzymać wysyłanie żądań do usługi na jakiś czas,
    • biblioteka kliencka może obsłużyć 503 Service Unavilable w podobny sposób.
  2. Pomimo, że standard nie odpowiada na wszystkie współczesne wymagania, wiele kodów odpowiedzi reprezentuje przypadki warte obsłużenia specjalną odpowiedzią – więc dlaczego nie skorzystać z istniejących już kodów?
    • jeżeli API zwraca kod 404 Not Found zamiast 405 Method Not Allowed, to zaczynam się zastanawiać czy źle wpisałem adres czy używam metody, która nie jest dozwolona,
    • zaoszczędzilibyśmy wiele godzin debugowania, gdybyśmy tylko otrzymywali 502 Bad Gateway, zamiast 500 Internal Server Error.
  3. Wierzcie mi lub nie, ale powstała nieformalna konwencja wśród najpopularniejszych API zwracania kodów takich jak 201 Created, 429 Too Many Requests i 503 Service Unavilable. Podążając nią użytkownicy będą mogli korzystać z naszych API w o wiele prostszy i bardziej intuicyjny sposób a znajdowanie i rozwiązywanie błędów będzie o wiele łatwiejsze.

Najtrudniejszą częścią tego całego procesu jest wybór kodu jaki należy zwrócić w odpowiedzi, jednak z odpowiednią wiedzą (patrz diagramy) właściwy wybór staje się o wiele prostszy.

Zobacz również

Pliki źródłowe diagramów