Opublikowane przez
REST i RESTful API to dość popularne buzzwordy w aktualnych czasach. W ramach przypomnienia, implementacje API zgodnie z założeniami architektury REST nazywamy RESTful API. Załóżmy, że wykonaliśmy implementacje API, skąd mamy mieć pewność, że jest w stylu REST. Kolega/koleżanka za monitora powie Ci, skoro masz HTTP i JSON to usługa internetowa musi być RESTful API. Czy to jest na pewno zgodne z prawdą? W powyższym artykule trochę rozjaśnię sytuacje omawiając RMM (Richardson Maturity Model). Leonard Richardson opracował RMM próbując sklasyfikować API zgodnie z przestrzeganiem ograniczeń nałożonych przez styl REST. Poniżej na rysunku zaprezentowałem ściągawka naszej wspinaczki na szczyt. Czy wasza usługa spełnia wszystkie wymagania i osiągnęła najwyższy poziom?
Level Zero
Zgodnie z Modelem Dojrzałości Richardsona, każde API należy do dowolnego z poziomów dojrzałości od poziomu 0 do poziomu 3. Im wyższy poziom został zaimplementowany tym bardziej nasze API jest zgodne z architekturą REST. Na poziomie 0 API nie spełnia założeń dla stylu architektury REST. API należące do tego poziomu nie wykorzystuje pełnego potencjału protokołu HTTP. Implementacja API nie opiera się na unikalnych adresach zasobów i HATEOAS. Do tego poziomu zaliczamy SOAP Service i XML-RPC API.
Level One
Na pierwszym poziomie modelu usługi wykorzystują wiele identyfikatorów URI, ale zazwyczaj tylko metody HTTP GET i POST. Powyższy poziom zakłada, że każdy zasób na serwerze posiada indywidualny identyfikator URI, co sprawia, że nasze API jest lepsze od poziomu 0, gdzie mieliśmy pojedynczy identyfikator URI dla każdego żądania od klienta. Warto pamiętać, ze zasób nie powinien być dostępny pod wieloma adresami, musi mieć unikalny adres.
POST http://localhost:56263/api/pictures/create POST http://localhost:56263/api/pictures/1/get POST http://localhost:56263/api/pictures/1/update POST http://localhost:56263/api/pictures/1/remove
Level Two
Ten poziom jest trochę mylący, bo REST nie jest uzależniony od protokołu. Używając inny protokół, API nadal może być w stylu REST. Dotychczas do implementacji RESTful API zawsze używałem protokołu HTTP. Na powyższym poziomie nie powinniśmy ograniczać się, wykorzystujmy dostępne metody, nagłówki i kody odpowiedzi HTTP. Do implementacji RESTful API będziemy stosować przede wszystkim metody POST, GET, PUT, PATCH i DELETE zgodnie z ich przeznaczeniem.
POST http://localhost:56263/api/pictures GET http://localhost:56263/api/pictures/1 PUT http://localhost:56263/api/pictures/1 PATCH http://localhost:56263/api/pictures/1 DELETE http://localhost:56263/api/pictures/1
W wyniku powyższych żądań nie powinniśmy zwracać tylko kodu odpowiedzi 200 (OK), jak to było na niższych poziomach. Na drugim poziomie modelu, API będzie zwracać status odpowiedzi zależnie od sposobu realizacji zapytania. Wyróżniamy następujące grupy kodów odpowiedzi HTTP:
- 1XX – Kody informacyjne;
- 2XX – Kody powodzenia;
- 3XX – Kody przekierowania;
- 4XX – Kody błędu aplikacji klienta;
- 5XX – Kody błędu serwera.
Level Three
Trzeci poziom (najwyższy) RMM wymaga implementacji HATEOAS (Hypertext As The Engine Of Application State). W wielu firmach trzeci poziom modelu nie jest realizowany, ze względu na dodatkową złożoność API. Firmy godzą się z tym że ich API znajduje się na 2 poziomie, tym samy nie jest to RESTful API. HATEOAS kieruje interakcją dla klienta. Klient API nie zna wszystkich punktów końcowych API, dla których może wykonać żądanie. Przeanalizujmy następujący przykład. Z dokumentacji API wiemy, pod jakim adresem możemy uzyskać kolekcje obrazów. Wykonujemy żądanie GET w wyniku, którego otrzymujemy strukturę z danymi identyfikującymi obrazy. Stosując HATEOAS dla pola identyfikującego obraz zamiast id otrzymamy adres do dodatkowych informacji dla powyższego zasobu. Przechodząc pod wybrany adres obrazu uzyskamy szczegółowe dane, gdzie np. zamiast identyfikatora twórcy obrazu otrzymamy link do zasobu reprezentującego malarza. Wykorzystując HATEOAS dostarczamy klientowi linki do poruszania się po API. Zastosowanie HATEOAS minimalizuje nam dokumentacje API. Usługa zaimplementowana na poziomie trzecim jest uważana za RESTful API.
Podsumowanie
Model Dojrzałości Richardsona pomaga programistom określić, na jakim poziomie znajduje się ich API. Znając aktualny poziom programista wie, co należy w API ulepszyć by osiągnąć wyższy poziom. Należy pamiętać, że nie każda usługa internetowa musi być typu RESTful, jeśli jednak zdecydowaliśmy się ja zaprojektować i wykonać, postarajmy spełnić jak najwięcej postulatów REST.