kontakt
Software house
>
Tag
>
RESTful co to znaczy? Co sprawia, że API określamy mianem RESTful?
RESTful

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

Data wpisu
Tomasz Kozon
Autor
Tomasz Kozon

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.

Restful API

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.

Case study: #restful
0 Aktualnie brak case study
Zobacz wszystkie

Wpisy z tagiem: restful