Czym jest REST?

RestWiki opisuje REST jako "styl projektowania architektury oprogramowania prezentującego informacje w sieci WWW".

Zasoby

Stan i funkcjonalność aplikacji jest podzielona na jednostki definiowane jako 'zasoby'.

Każdy zasób ma unikalny adres, w postaci uniwersalnego identyfikatora

Wszystkie zasoby używają jednolitego interfejsu do zmiany stanu, który składa się z

• Ograniczonego zbioru dobrze zdefiniowanych operacji
• Ograniczonego zbioru reprezentacji danych

Protokół

• typu klient/serwer
• bezstanowy
• keszowalny
• warstwowany

W praktyce, RESTowym można nazwać każdy protokół, który serwuje dane po HTTP, w wybranym formacie (np. JSON, YAML, XML), używający jednego URL na jeden logiczny zasób, i standardowych metod HTTP do korzystania z tych zasobów.

Tak właśnie działają kolejne API (poza galeriami) grono.net. Dla każdego logicznego obiektu, istnieje URL, na którym wykonywane są wszelkie operacje. Zwracane dane są w dobrze określonym formacie, czasem możliwym do wybrania z kilku alternatyw. Kod odpowiedzi HTTP określa status wykonania operacji.

Typowe dla Grona kody odpowiedzi

200 OK

Operacja wykonana poprawnie. W treści żądane dane.

201 Created

Operacja wykonana poprawnie, obiekt utworzony. W nagłówku Location może znajdować się URL nowego obiektu.

202 Accepted

Operacja przyjęta do realizacji. Zwracane przy niektórych operacjach których wykonanie nie jest natychmiastowe, czyli status jego powodzenia nie może zostać określony w czasie jednego requesta.

204 No Content

Operacja wykonana poprawnie, nie ma danych do zwrócenia. Odpowiedź jest generowana najczęściej przy modyfikacji zasobów.

400 Bad Request

Niepoprawnie sformułowane żądanie. Brak wymaganych parametrów, niepoprawny format parametrów lub danych wejściowych.

402 Payment Required

Korzystanie z zasobu wymaga wykupienia abonamentu Gronowładnego.

403 Forbidden

Brak autoryzacji. Nalezy sie zalogować. Używane zamiast 401, ponieważ ten header jest skojarzony z mechanizmen autoryzacji HTTP. Jeśli wprowadzona zostanie autentykacja HTTP, może zostać zastąpiony 401.

404 Not Found

Obiekt nie znaleziony, brak uprawnień lub nie można wygenerować żądanego formatu danych.

405 Method Not Allowed

Nieprawidłowa operacja na obiekcie. POST na obiekt który obsługuje tylko GET, lub w przypadku bardziej złożonych operacji, nieobsługiwany typ operacji. W szczególności zwracany przy próbie modyfikacji atrybutu tylko do odczytu.

409 Conflict

Obecny stan zasobu nie pozwala na dokonanie wskazanej akcji. Oznacza zatem, że istnieją ograniczenia co do ilości operacji w jednostce czasu, i właśnie zostały przekroczone. Używany zarówno w operacjach pobierających, jak i modyfikujących dane.

415 Unsupported Media Type

Nieobsługiwany format treści zapytania. Serwer nie potrafi przetworzyć danych wejściowych w podanym formacie. Zamiast 415 może wystąpić też 400 lub 500, które zasygnalizują podobny stan, ale z różnych przyczyn.

500 Internal Server Error

Błąd podczas realizacji żądania. Warto zgłosić do nas (korzystając z ticketów) sytuację, dodając dokładny opis danych wysyłanych.

503 Service Unavailable

Usługa wyłączona ze względu na konserwację. W odpowiedzi może być podany przewidywany czas włączenia usługi, w formacie ISO-8601.