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.