REST API pozwalają na stworzenie dowolnej aplikacji internetowej posiadającej wszystkie możliwe operacje CRUD (create, retrieve, update, delete). Wytyczne REST sugerują użycie konkretnej metody HTTP dla konkretnego typu połączenia z serwerem (choć technicznie możliwe jest naruszenie tej wytycznej, jednak jest to wysoce odradzane).
Użyj poniższych informacji, aby znaleźć odpowiednią metodę HTTP dla akcji wykonywanej przez API.
Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary
HTTP GET
Używaj żądań GET tylko do pobierania reprezentacji zasobu/informacji – a nie do modyfikowania go w jakikolwiek sposób. Ponieważ żądania GET nie zmieniają stanu zasobu, mówi się, że są to metody bezpieczne. Dodatkowo, API GET powinny być idempotentne, co oznacza, że wykonanie wielu identycznych żądań musi dać ten sam wynik za każdym razem, dopóki inne API (POST lub PUT) nie zmieni stanu zasobu na serwerze.
Jeśli Request-URI odnosi się do procesu produkującego dane, to wyprodukowane dane powinny być zwrócone jako jednostka w odpowiedzi, a nie tekst źródłowy procesu, chyba że ten tekst jest wyjściem procesu.
Dla każdego API HTTP GET, jeśli zasób jest znaleziony na serwerze, to musi zwrócić kod odpowiedzi HTTP 200 (OK) – wraz z ciałem odpowiedzi, które zwykle jest albo XML lub JSON (z powodu ich niezależnej od platformy natury).
W przypadku, gdy zasób NIE jest znaleziony na serwerze, to musi zwrócić kod odpowiedzi HTTP 404 (NOT FOUND). Podobnie, jeśli zostanie stwierdzone, że samo żądanie GET nie jest poprawnie sformowane, wówczas serwer zwróci kod odpowiedzi HTTP 400 (BAD REQUEST).
Przykładowe URI żądania
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/adres
HTTP POST
Używaj API POST do tworzenia nowych zasobów podrzędnych, np, plik jest podporządkowany katalogowi, który go zawiera lub wiersz jest podporządkowany tabeli bazy danych. Mówiąc ściśle w kategoriach REST, metody POST są używane do tworzenia nowego zasobu do kolekcji zasobów.
Idealnie, jeśli zasób został utworzony na serwerze źródłowym, odpowiedź POWINNA mieć kod odpowiedzi HTTP 201 (Created) i zawierać encję, która opisuje status żądania i odnosi się do nowego zasobu, oraz nagłówek Location.
Wielokrotnie akcja wykonywana przez metodę POST może nie skutkować zasobem, który można zidentyfikować za pomocą URI. W takim przypadku odpowiednim statusem odpowiedzi jest kod odpowiedzi HTTP 200 (OK) lub 204 (No Content).
Odpowiedzi na tę metodę nie są buforowane, chyba że odpowiedź zawiera odpowiednie pola nagłówka Cache-Control lub Expires.
Proszę zauważyć, że metoda POST nie jest ani bezpieczna, ani idempotentna, a wywołanie dwóch identycznych żądań POST spowoduje powstanie dwóch różnych zasobów zawierających te same informacje (z wyjątkiem identyfikatorów zasobów).
Przykładowe URI żądania
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Używaj API PUT przede wszystkim do aktualizacji istniejącego zasobu (jeśli zasób nie istnieje, to API może zdecydować o utworzeniu nowego zasobu lub nie). Jeśli nowy zasób został utworzony przez API PUT, serwer źródłowy MUSI poinformować agenta użytkownika poprzez kod odpowiedzi HTTP 201 (Created) i jeśli istniejący zasób jest modyfikowany, albo kody odpowiedzi 200 (OK) lub 204 (No Content) POWINNY być wysłane, aby wskazać pomyślne zakończenie żądania.
Jeśli żądanie przechodzi przez pamięć podręczną i Request-URI identyfikuje jeden lub więcej aktualnie zbuforowanych podmiotów, te wpisy POWINNY być traktowane jako nieaktualne. Odpowiedzi na tę metodę nie są buforowane.
Przykładowe URI żądania
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
Jak sama nazwa wskazuje, API DELETE są używane do usuwania zasobów (identyfikowanych przez Request-URI).
Pomyślną odpowiedzią żądania DELETE POWINNA być odpowiedź HTTP code 200 (OK), jeśli odpowiedź zawiera encję opisującą status, 202 (Accepted), jeśli akcja została umieszczona w kolejce, lub 204 (No Content), jeśli akcja została wykonana, ale odpowiedź nie zawiera encji.
Operacje DELETE są idempotentne. Jeśli usuniesz zasób, jest on usuwany z kolekcji zasobów. Wielokrotne wywołanie API DELETE na tym zasobie nie zmieni wyniku – jednakże, wywołanie DELETE na zasobie po raz drugi zwróci 404 (NOT FOUND), ponieważ został on już usunięty. Niektórzy mogą argumentować, że czyni to metodę DELETE nieidempotentną. Jest to kwestia dyskusji i osobistej opinii.
Jeśli żądanie przechodzi przez bufor i Request-URI identyfikuje jedną lub więcej aktualnie buforowanych jednostek, te wpisy POWINNY być traktowane jako nieaktualne. Odpowiedzi na tę metodę nie są buforowane.
Przykładowe URI żądania
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
ŻądaniaHTTP PATCH mają na celu częściową aktualizację zasobu. Jeśli widzisz, że żądania PUT również modyfikują encję zasobu, więc aby wyjaśnić – metoda PATCH jest właściwym wyborem dla częściowej aktualizacji istniejącego zasobu, a PUT powinna być używana tylko wtedy, gdy zastępujesz zasób w całości.
Pamiętaj, że istnieją pewne wyzwania, jeśli zdecydujesz się użyć API PATCH w swojej aplikacji:
- Wsparcie dla PATCH w przeglądarkach, serwerach i frameworkach aplikacji internetowych nie jest uniwersalne. IE8, PHP, Tomcat, Django i wiele innych programów ma brakujące lub uszkodzone wsparcie dla PATCH.
- Załadunek żądania PATCH nie jest tak prosty jak dla żądania PUT. np.
HTTP GET /users/1produkuje poniższą odpowiedź:
{id: 1, username: 'admin', email: ''}Przykładowe żądanie poprawki w celu zaktualizowania wiadomości e-mail będzie wyglądało następująco:
HTTP PATCH /users/1” }
]
Możliwe są następujące operacje według specyfikacji HTTP.
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
Metoda PATCH nie zastępuje metod POST lub PUT. Stosuje ona raczej deltę (diff) niż zastępuje cały zasób.
Podsumowanie metod HTTP dla RESTful APIs
Poniższa tabela podsumowuje użycie metod HTTP omówionych powyżej.
| MetodaHTTP | CRUD | Zbiór całkowity (np. /users) | Specific Item (np. /users/123) |
|---|---|---|---|
| POST | Create | 201 (Utworzony), nagłówek 'Location’ z linkiem do /users/{id} zawierający nowy identyfikator. | Unikaj używania POST na pojedynczym zasobie |
| GET | Read | 200 (OK), lista użytkowników. Użyj paginacji, sortowania i filtrowania do poruszania się po dużych listach. | 200 (OK), pojedynczy użytkownik. 404 (Not Found), jeśli ID nie znaleziono lub nieprawidłowe. |
| PUT | Update/Replace | 405 (Metoda niedozwolona), chyba że chcesz zaktualizować każdy zasób w całej kolekcji zasobów. | 200 (OK) lub 204 (Brak zawartości). Użyj 404 (Not Found), jeśli identyfikator nie został znaleziony lub jest nieprawidłowy. |
| PATCH | Partial Update/Modify | 405 (Metoda niedozwolona), chyba że chcesz zmodyfikować samą kolekcję. | 200 (OK) lub 204 (No Content). Użyj 404 (Not Found), jeśli ID nie zostało znalezione lub jest nieprawidłowe. |
| DELETE | Delete | 405 (Metoda niedozwolona), chyba że chcesz usunąć całą kolekcję – używaj z ostrożnością. | 200 (OK). 404 (Not Found), jeśli identyfikator nie został znaleziony lub jest nieprawidłowy. |
Glossary
Safe Methods
Zgodnie ze specyfikacją HTTP, metody GET i HEAD powinny być używane tylko do pobierania reprezentacji zasobów – i nie aktualizują/usuwają zasobów na serwerze. Obie metody uważa się za „bezpieczne”.
To pozwala agentom użytkownika reprezentować inne metody, takie jak POST, PUT i DELETE, w unikalny sposób, tak aby użytkownik był świadomy faktu, że żądana jest potencjalnie niebezpieczna akcja – i mogą one aktualizować/usuwać zasób na serwerze, więc powinny być używane ostrożnie.
Metody idempotentne
Termin idempotentny jest używany bardziej kompleksowo do opisania operacji, która da te same wyniki jeśli zostanie wykonana raz lub wiele razy. Idempotencja jest przydatną właściwością w wielu sytuacjach, ponieważ oznacza, że operacja może być powtarzana lub próbowana tak często, jak to konieczne, bez powodowania niezamierzonych efektów. W przypadku operacji nieidempotentnych algorytm może być zmuszony do śledzenia, czy dana operacja została już wykonana, czy nie.
W specyfikacji HTTP metody GET, HEAD, PUT i DELETE są zadeklarowane jako metody idempotentne. Inne metody OPTIONS i TRACE NIE POWINNY mieć skutków ubocznych, więc obie są również z natury idempotentne.