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 aplikacji, którą mam zamiar napisać jest właśnie REST API. W moim projekcie mam zamiar użyć do tego celu node.js oraz MongoDB. Miałem już co nieco do czynienia z obiema technologiami, natomiast chcę nauczyć się ich w stopniu bardzo dobrym i liczę, że ten projekt pomoże w nauce zarówno mi jak i czytelnikom tego bloga.

Chciałbym, aby ten wpis stał się pierwszym z serii wpisów o tej tematyce. Kolejne wpisy będą publikowane w miarę postępów podczas tworzenia projektu. Chcę również postawić na jakość zgodnie z tym, co napisałem we wpisie Case study moich doświadczeń z blogowaniem.

Gotowy? 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 programami komputerowymi.

Czyli API są to 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 jak zbudowane będzie to API.

HTTPHypertext Transfer Protocol – protokół, z którego korzystasz codziennie (lub też jego wersji szyfrowanej – HTTPS) podczas przeglądania stron w sieci. Podczas tworzenia REST API do komunikacji z API wykorzystuje się metody HTTP, których łącznie jest 9. Niemniej jednak do zbudowania podstawowego API pozwalającego na odczyt, zapis, aktualizację i usuwanie danych wystarczą tylko 4 metody – GET, POST, PUT i DELETE.

Zasada działania API

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

  1. Klient preparuje zapytanie w postaci odpowiedniego adresu (endpointa).
  2. Następnie wysyła to zapytanie do interfejsu.
  3. Interfejs zwraca odpowiedź na zapytanie klienta.
  4. Klient otrzymuje odpowiedź na swoje zapytanie.

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ży API.

REST API HTTP - zielona kłódka

Metody HTTP

Z racji, że jest to tylko wstęp do tematu ograniczę się do 4 absolutnie podstawowych metod HTTP. Są to metody, które na 100% będę wykorzystywał w swoim projekcie:

GET – służy do pobierania danych. Tutaj wystarczy podać odpowiedni endpoint, ewentualnie zmodyfikować nagłówki(headers) zapytania.

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.

PUT – również służy przesyłaniu danych, lecz najczęściej w celu aktualizacji tych danych. Tutaj również wymagane jest przesłanie danych w ciele

DELETE – metoda służąca do usuwania danych. W tym momencie chcę wspomnieć o technice tak zwanego soft-delete. 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.
  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 tak naprawdę adresy, które pozwalają na dostęp do informacji 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 oraz prezentacji. Pozwala to na dowolne operacje na danych – nie wymuszamy na użytkowniku konkretnego działania na nich, ani wyświetlania ich w konkretny sposób. Ponadto pośrednie i zewnętrzne API wykorzystywane przez serwer(!) mogą być wykorzystywane bez wiedzy klienta. Przykładem może być wcześniej wspomniany samolot, gdzie informacja np. o kolorze może pochodzić z zupełnie innego API – klient nie musi o tym wiedzieć.
  6. Możliwość udostępniania apletów i skryptów klientowi – jest to opcjonalna reguła, aczkolwiek 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 - kciuk w górze

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.

Największą z zalet jest przede 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 – jeśli napisany interfejs programistyczny jest zgodny z zasadami REST, to w trakcie procesu pisania aplikacji będziesz intuicyjnie tworzył endpointy i dzięki nim wygodnie operował na danych.

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 spotykam się z nim coraz rzadziej. Korzystanie z JSON’ów jest naprawdę szybkie, wygodne i nie powoduje większych trudności.

Możemy 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.

REST API - popularne media społecznościowe

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 Star Wars.
    • 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ś 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. Zachęcam również do konstruktywnej i merytorycznej krytyki oraz do dyskusji nad omawianym tematem w komentarzach.

Ź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