Wstęp do REST API - okładka

Wstęp do REST API

Dlaczego akurat wpis o REST API?

Na stworzenie tego wpisu zdecydowałem się po podjęciu decyzji o rozpoczęciu mojego nowego projektu. Jednym z elementów projektowanej aplikacji jest właśnie REST API. W tym wpisie chcę podzielić się zdobytymi doświadczeniami z czytelnikami. Oprócz tego wpis ten traktuję jako swoiste ugruntowanie zdobytej wiedzy, które pomoże nie tylko mi ale także czytelnikom tego bloga.

Gotowy/a? W takim razie zaczynajmy…

REST API - start

Rozszyfrowanie skrótów

Na początek, aby wiedzieć co jest czym i skąd pochodzi należy sobie odpowiedzieć na pytanie co oznacza skrót z tytułu tego wpisu oraz skróty z nim powiązane:

REST – Representational State Transfer – styl architektury oprogramowania, opierający się o zbiór wcześniej określonych reguł opisujących jak definiowane są zasoby, a także umożliwiających dostęp do nich. Został on zaprezentowany przez Roya Fieldinga w 2000 roku.

APIApplication Programming Interface – zestaw reguł definiujący komunikację pomiędzy systemami komputerowymi oraz pomiędzy systemem komputerowym a człowiekiem.

Słowem podsumowania – API definiuje jak użytkownik może skomunikować się z systemem, reguły określające jak użytkownik może uzyskać dostęp do zasobów oraz w jakiej postaci je otrzymuje. Natomiast REST to styl architektury definiujący kształt API.

Ostatnim akronimem, nierozerwalnie powiązanym z tematem REST API jest HTTP. Hypertext Transfer Protocol to protokół, z którego korzystasz codziennie (lub też jego wersji szyfrowanej – HTTPS) podczas przeglądania stron w sieci (nawet teraz). Podczas tworzenia REST API, do komunikacji wykorzystuje się metody HTTP, których łącznie jest 9:

  • GET
  • POST
  • PUT
  • DELETE
  • CONNECT
  • OPTIONS
  • TRACE
  • PATCH
  • HEAD

Niemniej jednak do zbudowania podstawowego API, pozwalającego na: odczyt, zapis, aktualizację i usuwanie danych wystarczą tylko 4 metody – GET, POST, PUTDELETE.

Zasada działania API

Cykl pracy z API możemy określić następująco:

  1. Klient preparuje zapytanie w postaci odpowiedniego adresu (endpoint),
  2. Klient wysyła przygotowane zapytanie (request),
  3. System otrzymuje zapytanie klienta i przygotowuje odpowiedź (response),
  4. System zwraca odpowiedź na zapytanie klienta,
  5. Klient otrzymuje i przetwarza odpowiedź.

Dla wielu osób to, co napisałem może się wydawać oczywiste. Chciałbym jednak, aby KAŻDY po przeczytaniu tego artykułu wiedział do czego służą i jak działają API.

REST API HTTP - zielona kłódka

Metody HTTP

Z racji, że jest to tylko wstęp do tematu ograniczę się do 4 podstawowych metod HTTP, które spotykane są sporej większości REST API:

GET – jak samam nazwa mówi służy do pobierania danych. Tutaj wystarczy podać odpowiedni endpoint, ewentualnie zmodyfikować nagłówki (headers) oraz parametry (query params) zapytania. Przykładowe zapytanie możę wyglądać następująco http://example.com/api/resource?per_page=10&page=2. Bardzo częstym przypadkiem użycia metody GET jest weryfikacja czy dany zasób istnieje czy też nie. Jednak moim zdaniem zdecydowanie lepszym pomysłem w tej sytuacji jest skorzystanie z metody HEAD. Główną różnicą pomiędzy tymi metodami jest to, że odpowiedź na zapytanie HEAD zawiera tylko nagłówk, które w opisanym przypadku są wystarczające. Jedyne co tak naprawdę potrzebujemy to kod odpowiedzi, na przykład 200 w przypadku gdy zasób istnieje lub 404 gdy podany zasób nie istnieje.

POST – służy tworzeniu i przesłaniu nowych danych. W tym przypadku konieczne jest już stworzenie ciała (body), w którym przekażemy dane do naszego REST API. W odpowiedzi powinien zostać zwrócony nagłówek HTTP Location z adresem do nowo utworzonego zasobu.

PUT – bardzo podobna do metody POST. Główną cechą odróżniającą PUT jest to, że zapytanie PUT musi wskazywać na konkretny zasób. PUT jest używany głównie do aktualizowania istniejących zasobów. Wartym wspomnienia jest fakt, że PUT nadpisuje cały zasób – dla częściowego nadpisania służy metoda PATCH.

DELETE – metoda służąca do usuwania danych. W tym momencie chcę wspomnieć o technice tak zwanego soft-delete o którym na moim blogu powstał wpis Co nieco o soft delete przy użyciu Node.js i MongoDB. Mówiąc skrótem polega to na tym, że kasując dane za pomocą API tak naprawdę tylko dodajemy do encji informację o tym, że została ona usunięta. W rezultacie dane pozostają nadal w bazie, lecz nie są one dostępne z poziomu API. Mechanizm ten należy już zaimplementować w samym API i nie ma on nic wspólnego z HTTP.

Zasady tworzące REST

Aby API można nazwać RESTful lub API RESTowym musi ono spełniać kilka założeń:

  1. Odseparowanie interfejsu użytkownika od operacji na serwerze. Klient poprzez “wydawanie poleceń” nie ma wpływu na to co się dzieje po stronie serwera. Działa to również w drugą stronę – serwer daje klientowi jedynie odpowiedź i nie ma prawa ingerować w UI. Pozwala to na korzystanie z jednego REST API w wielu niezależnych od siebie aplikacjach, a dane pozostaną spójne.
  2. Bezstanowość – mówi się że REST jest stateless – oznacza to, że każde zapytanie od klienta musi zawierać komplet informacji oraz, że serwer nie przechowuje stanu o sesji użytkownika po swojej stronie. W REST nie istnieją takie pojęcia jak chociażby stany czy sesje.
  3. Cacheability – odpowiedź, którą użytkownik otrzyma z REST API musi jasno definiować, czy ma ona być cacheable czy non-cacheable. Ma to znaczenie przy danych, które bardzo szybko stają się nieaktualne oraz przy danych, które aktualizują się relatywnie rzadko – nie ma sensu na przykład cache’ować współrzędnych geograficznych pędzącego samolotu, natomiast już jego kolor czy nazwę już tak.
  4. Endpointy, czyli adresy zasobów, powinny jednoznacznie wskazywać do jakiego zasobu się odwołują. Z ich budowy powinniśmy wiedzieć jaki konkretnie zasób otrzymamy. Co ważne – dane otrzymywane w API powinny być niezależne w żaden sposób od schematu bazy danych w jakiej są przetrzymywane. Oczywiście nie ma przeciwwskazań, aby struktura danych wyglądała identycznie jak schemat bazy danych – niemniej jednak struktura w żaden sposób nie powinna zależeć od tego schematu.
  5. Separacja warstw – powinniśmy oddzielić warstwy dostępu do danych, logiki biznesowej oraz prezentacji. Żadna z warstw nie powinna bezpośrednio oddziaływać na inne warstwy. Użycie (implementacja) pośrednich i zewnętrznych API powinny być ukryte. Przykładem może być wcześniej wspomniany samolot. Dla przykładu, informacja o kolorze może pochodzić z zupełnie innego API – klient nie musi o tym wiedzieć.
  6. Możliwość udostępniania adapterów i skryptów użytkownikom. Jest to opcjonalna reguła, aczkolwiek zdecydowanie warto rozważyć jej zastosowanie. Jeśli wiemy, że klienci będą wykonywać konkretne operacje na konkretnych danych możemy im udostępnić gotowe do tego rozwiązania.

Zalety korszytania z REST API

Jakie są zalety korzystania z REST API?

Korzystanie z tego rozwiązania ma swoje zalety – gdyby nie miało to nikt by tego nie używał, oraz nie pisałbym tego artykułu. Nie bez przyczyny architektura SOAP została wyparta z rynku właśnie na rzecz RESTa.

Największą z zalet RESTa jest wszystkim uniwersalność. Załóżmy, że potrzebujesz stworzyć aplikację na telefon i stronę internetową dla księgarni. Możesz stworzyć jedno API, z którego będzie korzystała zarówno aplikacja jak i strona internetowa!

Po drugie, prawdziwie RESTowe interfejsy są intuicyje i wygodne w użytkowniu. Intuincyjny interfejs znacznie ułatwia integrację z naszym API, a także redukuje czas poświęcony na czytanie dokumentacji.

Dane jakie otrzymujemy z API, najczęściej są w wygodnym do pracy formacie – JSON, czyli JavaScript Object Notation. Czasami zdarzy się jeszcze format XML, niemniej jednak kojarzy się on bardziej z architekturą SOAP. Korzystanie z JSON’ów jest naprawdę komfortowe, intuicyjne i nie powoduje większych trudności.

Możemy równie pozyskiwać dane jednocześnie z wielu źródeł. Na przykład możemy stworzyć aplikację wykorzystującą logowanie za pomocą Facebooka oraz mapy Google. W obu przypadkach skorzystamy z API oferowanych przez te firmy.

Kolejną z zalet jest możliwość odseparowania warstwy klienta, od warstwy serwerowej. Alternatywą dla API jest tworzenie widoków za pomocą silników szablonów takich jak Pug, Twig, czy Blade.

Ostatnią, z wymienionych zalet będzie możliwość banalne łatwego testowania endpoint’ów. Powstały naprawdę świetne i bardzo rozbudowane narzędzia do tego celu. Moim ulubionym jest Postman, któremu w przyszłości mam zamiar poświęcić osobny, obszerny wpis. Dla fanów konosolowych rozwiązań istnieje narzędzie cURL.

REST API - Ikony mediów społecznościowych

Przykłady popularnych API

    • Google Geolocation API,
    • YouTube Data API,
    • WordPress REST API – napisałem o nim artykuł Rzut okiem na WordPress REST API,
    • SWAPI – zawiera postaci, planety, pojazdy itp. z uniwersum Gwiezdnych Wojen,
    • Cały szereg interfejsów przygotowanych przez Facebooka.

Przykłady mógłbym tu wypisywać w nieskończoność, jednak zachęcam Cię do wypróbowania co najmniej jednego z nich!

Kilka słów podsumowania

Dziękuję Ci, że dotrwałeś do tego momentu. Mam nadzieję, że dowiedziałeś/aś się dzięki temu artykułowi czegoś nowego, a co ważniejsze, czegoś co Ci się przyda. Jeśli masz jakieś pytania lub wątpliwości – napisz mi o tym w komentarzu. Zapraszam również do dyskusji nad omawianym tematem w komentarzach.

Uzupełnienie

Z razcji, że wpis jest szalenie popularny, a od czasu jego publikacji minęło sporo czasu zdecydowałem się na mały refactor. Myślę, że wprowadzone poprawki pozytywnie wpłyną na merytorykę wpisu, przez co stanie się on jeszce bardziej przydatny. W tym miejscu chciałbym podziękować wszystkim komentującym ten wpis, ponieważ to dzięki Wam doczekał się on uzupełnienia i aktualizacji.

Źródła i materiały dodatkowe:

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
https://youtu.be/0oXYLzuucwE
https://restfulapi.net/
https://www.service-architecture.com/articles/web-services/representational_state_transfer_rest.html
https://pl.wikipedia.org/wiki/Hypertext_Transfer_Protocol
https://devenv.pl/devcast-13-jak-projektowac-webapi/
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md