Podręcznik

Operacje na zasobach najczęściej należą do kategorii określanych akronimem CRUD, pochodzącym od określeń typowych operacji:

• Create - utworzenie zasobu,
• Read - odczytanie, pobranie zasobu,
• Update - aktualizacja zasobu,
• Delete - usunięcie zasobu.
  

API budowane w stylu REST wykorzystuje metody HTTP do realizacji operacji CRUD na zasobach:

• GET - pobranie zasobu,
• POST - utworzenie nowego zasobu,
• PUT - aktualizacja istniejącego zasobu,
• PATCH - częściowa aktualizacja zasobu,
• DELETE - usunięcie zasobu.

Odpowiedzi odsyłane przez serwer opatrzone są zawsze tzw. kodem statusu (HTTP response status code). Przyjrzyjmy się kodom, które najczęściej są stosowane w projektowaniu interfejsów RESTful API.

1xx – Kody informacyjne

Kody tej grupy rzadko są stosowane, ponieważ w interfejsach RESTful API zazwyczaj nie wymaga się zaawansowanego sterowania przepływem informacji w trakcie obsługi żądania.

2xx – Kody sukcesu

Kody tej grupy wskazują, że żądanie zostało pomyślnie przetworzone przez serwer.

200 OK

• Żądanie zostało pomyślnie przetworzone i serwer zwraca oczekiwane dane.
• Przykład użycia:
  • GET /users/123
    GET /users/123 – Zwraca dane użytkownika o ID
    123
    123
  • PUT /users/123
    PUT /users/123 – Zaktualizowano dane użytkownika

201 Created

• Żądanie zostało przetworzone i zasób został pomyślnie utworzony.
• Przykład użycia:
  • POST /users
    POST /users – Utworzono nowego użytkownika
  • Odpowiedź powinna zawierać nagłówek
    Location
    Location wskazujący URI nowo utworzonego zasobu (np.
    Location: /users/123
    Location: /users/123)

202 Accepted

• Żądanie zostało zaakceptowane do przetworzenia, ale operacja nie została jeszcze zakończona.
• Przykład użycia:
  • POST /tasks
    POST /tasks – Zadanie zostało przyjęte do przetworzenia, ale serwer jeszcze go nie ukończył.

204 No Content

• Żądanie zostało pomyślnie przetworzone, ale serwer nie zwraca żadnych danych.
• Przykłady użycia:
  • DELETE /users/123
    DELETE /users/123 – Użytkownik został usunięty, w związku z tym nie ma informacji do zwrócenia
    
  • PUT /users/123
    PUT /users/123 – Zaktualizowano dane użytkownika, ale nie ma potrzeby zwracania dodatkowych informacji

3xx – Kody przekierowania

Kody te są używane w przypadkach, gdy zasób został przeniesiony lub serwer wymaga dodatkowego działania ze strony klienta.

301 Moved Permanently

• Zasób został trwale przeniesiony do nowego URI
• Przykład użycia:
  • GET /old-resource
    GET /old-resource – Zwraca kod 301 z nagłówkiem
    Location: /new-resource
    Location: /new-resource

302 Found

• Ten kod odpowiedzi oznacza, że URI żądanego zasobu został tymczasowo zmieniony. Dalsze zmiany w URI mogą zostać wprowadzone w przyszłości, więc ten sam URI powinien być używany przez klienta w przyszłych żądaniach.
  
• Przykłady użycia:
  • Może być użyte do przekierowania na tymczasową lokalizację zasobu.

304 Not Modified

• Zasób nie został zmieniony od ostatniego żądania.
• Przykłady użycia:
  • Nagłówek ten jest używany do celów buforowania. Informuje klienta, że odpowiedź nie została zmodyfikowana, więc klient może nadal korzystać z tej samej buforowanej wersji odpowiedzi. Serwer może nie odsyłać samego zasobu, a przeglądarka natychmiast wykorzysta zasób przechowywany w lokalnej pamięci cache.

4xx – Kody błędów klienta

Kody te wskazują, że przyczyna problemu leży po stronie klienta, np. żądanie zostało nieprawidłowo skonstruowane lub nie podano właściwych danych do autoryzacji.

400 Bad Request

• Żądanie jest niepoprawne lub niezgodne z wymaganiami API.
• Przykłady użycia:
  • POST /users
    POST /users – Brak wymaganych danych w ciele żądania
  • GET /users/abc
    GET /users/abc – Nieprawidłowy identyfikator (np.
    abc
    abc zamiast liczby)

401 Unauthorized

• Klient nie został uwierzytelniony
• Przykład użycia:
  • GET /users
    GET /users – Klient nie dostarczył tokena autoryzacyjnego w nagłówku
    Authorization
    Authorization.

403 Forbidden

• Klient nie ma uprawnień do wykonania żądania, nawet jeśli jest uwierzytelniony.
• Przykład użycia:
  • DELETE /users/123
    DELETE /users/123 – Użytkownik zalogowany jako zwykły użytkownik próbuje usunąć innego użytkownika, ale brak mu odpowiednich uprawnień

404 Not Found

• Żądany zasób nie został znaleziony na serwerze.
• Przykłady użycia:
  • GET /users/999
    GET /users/999 – Użytkownik o ID
    999
    999 nie istnieje.
  • GET /non-existing-resource
    GET /non-existing-resource – Zasób nie istnieje.

405 Method Not Allowed

• Metoda HTTP użyta w żądaniu nie jest obsługiwana dla danego zasobu.
• Przykłady użycia:
  • PUT /users
    PUT /users – Metoda PUT nie jest dozwolona dla kolekcji użytkowników (ale może być dozwolona dla
    /users/{id}
    /users/{id}).

5xx – Kody błędów serwera

Kody te wskazują, że przyczyna problemu leży po stronie serwera.

500 Internal Server Error

• Ogólny błąd serwera wskazujący, że serwer nie może przetworzyć żądania (bez wskazania bardziej szczegółowej przyczyny).
• Przykład użycia:
  • Wystąpił nieoczekiwany błąd po stronie serwera podczas przetwarzania żądania, np. rzucony został wyjątek, który nie został nigdzie obsłużony.

501 Not Implemented

• Metoda żądania nie jest obsługiwana przez serwer i nie może zostać obsłużona. 
• Jedynymi metodami, które serwery muszą obsługiwać (i dlatego nie mogą zwracać tego kodu) są GET i HEAD.
  
• Przykład użycia:
  • Serwer powinien zwracać ten kod w przypadku, gdy otrzyma żądanie np. typu PUT, którego obsługa nie została zaimplementowana w kontekście danego zasobu.
    

503 Service Unavailable

• Serwer jest tymczasowo niedostępny (np. z powodu konserwacji lub przeciążenia).
• Przykłady użycia:
  • Serwer API jest wyłączony w celu przeprowadzenia konserwacji.

Pełne zestawienie kodów odpowiedzi protokołu HTTP wraz z ich omówieniem znajdziesz na portalu MDN w artykule: HTTP response status codes.