
RESTful co to znaczy? Co sprawia, że API określamy mianem RESTful?

RESTful oznacza, że dane API jest w pełni zgodne ze standardem REST. Standard wytwarzania oprogramowania REST odnosi się w szczególności do stron internetowych. Aby można było stwierdzić, że napisane przez nas API spełnia standardy REST musi w praktyce spełniać poniższe wymagania:
- Unikalne metody za pomocą których odpytuje API takie jak GET, PUT, DELETE, PATCH określane jako ujednolicony interfejs
- Dane zapytanie jest niezależne od stanu aplikacji, zawsze zwraca to samo, czyli jeżeli zapytamy o zasób o ID=1 w API to niezależnie od tego czy jesteśmy użytkownikiem A czy B powinniśmy uzyskać to samo
- API zwraca komunikaty o tym czy dane zapytanie odniosło sukces czy też zwróciło błąd. API powinno wskazać dokładnie co to był za błąd.
- Zapytanie do API powinno jednoznacznie określać jaki rodzaj zasobu odpytuje i dla odpytywania książek będziemy używać innego
- Klient nie wchodzi bezpośrednio w żadną interakcję z zasobami serwera
- Możliwość używania cache. API musi zwracać informację czy dany zasób jest zachowany i czy może być zachowany
Warto pamiętać, że REST to nie to samo co HTTP, a także REST nie narzuca w żaden sposób typu danych które są zwracane z API. Może to być zarówno JSON jak i zwykły tekst.
Jak wygląda zapytanie typu REST do API
Każde zapytanie API powinno posiadać następujące elementy:
- Nazwę endpointu
- Rodzaj metody
- Nagłówki
- Dane
Przykładowym zapytaniem typu GET będzie
curl -H "Authorization: OAuth <ACCESS_TOKEN>" http://www.example.com/users/2
Praktyczne wskazówki RESTful
Wiele jest ogólników dotyczących RESTful API, ale ciężko znaleźć dobre materiały, które by wskazywały co zrobić by w rzeczywistości nasze API spełniało standardy REST.
Konstrukcja URL w RESTful API
Jedną z najważniejszych rzeczy jest konstrukcja URLa. Url powinien mieć:
- korzystamy tylko z małych liter
- wykorzystujemy myślnik ( - ) zamiast podkreślenia ( _ )
- nie dodajemy typu zwracanych danych do naszego urla, zamiast tego powinno się wykorzystywać Content-Type w headerze
- wykorzystujemy liczbę mnogą w nazwie dla nazw kolekcji np /books/
- wykorzystujemy liczbę pojedyncza dla nazw dokumentów np /books/sciencefiction/
- nie wykorzystujemy metody typu create, delete w nazwie np. błędem jest zrobienie /deletebook/
- możemy wersjonować i powinniśmy dodawać główną wersję api do nazwy np. /v1/books/
Zwracane kody odpowiedzi
API powinno zwracać kody odpowiedzi. Standardem są odpowiedzi zawierające kody błędów o numerach od 2xx, 3xx, 4xx, 5xx. Wszystkie poza odpowiedziami z grupy 200 oznaczają, że w naszym API wystąpił jakiś błąd.