Wprowadzenie do API HTTP oraz REST API
API, API HTTP, REST API, RESTfulAPI - jestem pewien, że spotkałaś/spotkałeś się z tymi określeniami wiele razy, ale czy wiesz, co oznaczają? Może Cię zaskoczę, ale wszystkie te określenia w gruncie rzeczy określają tą samą rzecz. Interfejsy API są najpopularniejszym sposobem komunikacji programów i urządzeń w świecie internetu. W tym artykule postaram Ci się wytłumaczyć, czym jest API w najprostszy możliwy sposób.
W jaki sposób, strona internetowa komunikuje się z API
Wyobraź sobie stronę internetową, która pozwala na zapisywanie domowych wydatków. Jako użytkownik możesz się zalogować, a następnie przeglądać, edytować i dodawać wydatki. Oczywiście możesz robić to z dowolnego komputera czy telefonu. Aby było to możliwe, strona internetowa musi przesłać informacje z Twojej przeglądarki internetowej do serwera, który je zapisze najprawdopodobniej w bazie danych. Taki schemat mógłby wyglądać tak:
W jaki sposób, w takim razie strona internetowa komunikuje się z aplikacją serwerową? Wykorzystują do tego protokół HTTP oraz podstawowe jego metody takie jak POST, GET, PUT, DELETE. Aplikacja serwerowa działa jako serwer i udostępnia tzw. API, a strony internetowe jako klienci. Klientami nazywamy usługi korzystające z API.
Czym jest interfejs API
Interfejs API, czyli application programming interface, jest zestawem reguł definiujących sposób, w jaki aplikacje mogą się ze sobą komunikować. Określa, jak klient może uzyskać dostęp do zasobów oraz w jakiej postaci je otrzymuje. API to nic innego jak implementacja w kodzie aplikacji serwerowej. Określa jakie żądania aplikacja może obsłużyć, jakie dane zwrócić, jakie przyjąć itd.
Zasada działania jest zasadniczo prosta. Aplikacja serwerowa nasłuchuje i czeka na wszelkie żądania (ang. requests) wysyłane przez swoich klientów. W momencie otrzymania konkretnego żądania obsługuje je, wykonując odpowiednią akcję. Na przykładzie naszej aplikacji do zarządzania budżetem domowym: gdy logujesz się do aplikacji, a następnie dodajesz nowy wydatek, strona internetowa wysyła żądanie do aplikacji serwerowej, aby zapisała podany wydatek do bazy danych. Gdy tylko chcesz odczytać istniejące wydatki, strona internetowa wysyła do serwera żądanie o pobranie Twoich wydatków z bazy danych, a następnie przesłanie ich.
Aplikacja serwerowa posiada unikalny adres w sieci, dzięki czemu każdy klient wie dokładnie, gdzie należy wysłać żądanie. Dodatkowo każda możliwa operacja jak dodanie wydatku, edycja itd jest ściśle określona przez aplikację serwerową. Aplikacja definiuje jakie akcje może wykonać, jakie dane przyjmuje oraz jakie dane zwraca.
Przykład komunikacji z API HTTP
Klient przygotowuje żądanie, które chce wysłać do aplikacji serwerowej. Aby to zrobić, musi znać dokładny adres w sieci, pod którym działa aplikacja serwerowa oraz jakich danych oczekuje. Zazwyczaj wiadomo jest to z dokumentacji API.
Klient wysyła żądanie.
Aplikacja serwerowa przyjmuje żądanie i wykonuje odpowiednią akcję. To jaką akcje należy wykonać, określa bezpośrednio implementacja API przygotowana przez programistę. Np. połączenie się do wybranej bazy danych i zapisanie wydatku.
Aplikacja serwerowa zwraca odpowiedź do klienta, informując, z jakim statusem została zakończona operacja. Operacja może zakończyć się pozytywnie, jak również może wystąpić błąd. Zazwyczaj wykorzystuje się HTTP Status Code do określenia statusu operacji.
Klient odbiera odpowiedź aplikacji serwerowej i odpowiednio ją przetwarza. W przypadku błędu może np. wyświetlić odpowiedni komunikat użytkownikowi.
Całą operację można porównać do wysyłania listu. Protokół HTTP udostępnia znormalizowany sposób komunikowania w internecie i można go porównać do wypełnienia danych na kopercie listu oraz znaczka. Sposób, w jaki należy to zrobić, jest znormalizowany i z góry znany każdemu, kto chce wysłać list. Odbiorca listu musi zostać podany i reprezentuje on naszą aplikację serwerową, która jest odbiorcą żądania (listu). Rolę poczty, która dostarcza list, odgrywa w świecie sieć internetowa. Mam nadzieje, że rozumiesz ten przykład.
Czym są metody HTTP
Czym w takim razie są wspomniane metody HTTP takie jak: POST, GET, PUT, DELETE? Metody HTTP są typami akcji, (żądań) jakie możemy przesłać do aplikacji serwerowej jako klienci. Każda z metod ma pewne swoje właściwości i określone zastosowanie. Oczywiście jest to sprawa umowna, ponieważ jest możliwość zrealizowania wszystkich żądań za pomocą metody POST. Takie podejście byłoby jednak nieczytelne i mylące dla klientów API, którzy oczekują pewnego standardu obsługi żądań.
Metody HTTP
GET: metoda GET służy do pobierania danych. Przykładowe zapytanie może wyglądać następująco: http://your_api.com/api/resource?page_number=1. Metoda GET zoptymalizowana jest pod względem pobierania danych, dlatego pozwala przesyłać do serwera parametry filtrowania w postaci ‘queryparameters’. Są to parametry na zasadzie klucz wartość - parameter_name=value, które możesz przesłać w zapytaniu. Wyobraź sobie przypadek, w którym chciałbyś/chciałabyś pobrać z serwera listę wydatków z wybranego dnia. Aby to zrealizować, musisz przesłać do serwera odpowiednie żądanie, w którym określisz jaki zasób chcesz pobrać oraz podasz wybraną datę. Przykładowe zapytanie mogłoby wyglądać następująco: http://your_api.com/api/expenses?expense_date=your_date.
POST: metoda POST służy do tworzenia i wysyłania danych. Możesz ją wykorzystać w przypadku np. Gdy chcesz stworzyć nowy wydatek w systemie. Metoda POST zawiera ciało (tzw. Body), które jest niczym innym jak pojemnikiem na dane, które wysyłasz.
PUT: metoda PUT służy do modyfikacji istniejących zasobów. Każde zapytanie musi jasno wskazywać jaki konkretny zasób chcemy zmodyfikować. Przykładowe żądanie mogłoby wyglądać następująco: http://your_api.com/api/expenses/id_zasobu Body: dane, jakie chcemy wysłać. Np. w formacie JSON.
DELETE: metoda DELETE służy do usuwania istniejących zasobów. Każde zapytanie musi jasno wskazywać jaki konkretny zasób chcemy usunąć. Przykładowe żądanie mogłoby wyglądać następująco: http://your_api.com/api/expenses/id_zasobu
Przykład implementacji REST API w node.js
Czym jest REST API
REST, czyli Representational State Transfer, jest stylem architektury oprogramowania, opierający się o zbiór wcześniej określonych reguł opisujących jak definiowane są zasoby. To nic innego jak po prostu zbiór pewnych zasad i praktyk, które musi spełniać API, aby można było je nazwać RESTful API.
Zasady REST
Separacja klienta od serwera: klient może jedynie komunikować się z API za pomocą z góry określonych żądań, nie ma możliwości kontrolowania tego, co dzieje się po stronie serwera. Dzięki temu podejściu jedno API może być wykorzystywane przez wielu różnych klientów, którzy dostosują się do kontraktu.
Bezstanowość - REST API powinno być statless - czyli nie posiadać stanu. Oznacza to, że klient wykonujący żądanie musi podać wszystkie wymagane dane, aby możliwe było wykonanie akcji. REST API nie przechowuje sesji użytkownika po stronie serwera.
Cacheability - wszystkie zasoby powinny zezwalać na buforowanie, chyba że wyraźnie wskazano, że nie jest to możliwe.
System warstwowy - REST pozwala na separacje warstw. Polega to na tym, że wybrana metoda API może wewnętrznie odwoływać się do kolejnego API, natomiast klient o tym nie musi wiedzieć.
Jednolity interfejs - zasoby powinny być jednoznacznie identyfikowalne za pomocą pojedynczego adresu URL i tylko przy użyciu podstawowych metod protokołu HTTP, takich jak DELETE, PUT i GET itd.
W większości przypadków serwer zwraca statyczne dane w formacie XML lub JSON. Jednak w razie potrzeby API może zwrócić klientowi kod wykonywalny. Jest to opcjonalna reguła.
Dlaczego znajomość API HTTP jest taka ważna
Interfejsy API są najpopularniejszym sposobem komunikacji programów i urządzeń w świecie internetu. Niezależnie z jakim językiem pracujesz oraz w jakiej firmie, jestem pewien, że spotkasz się z tym rozwiązaniem. Największą z zalet API jest uniwersalność i skalowalność. API buduje pewnego rodzaju warstwę abstrakcji, która pozwala odciąć się od danego języka programowania. Jedna aplikacja serwerowa udostępniająca API może być napisana w innym języku niż klient, który z niej korzysta. Co więcej, każdy klient może również wykorzystywać inny język programowania. Praca z REST API jest prosta i intuicyjna dzięki zachowaniu określonych standardów podczas jego tworzenia. Istnieje również bardzo dużo darmowych narzędzi, które umożliwiają połączenie się do API HTTP oraz pracę z nim. Jednym z najpopularniejszych narzędzi jest Postman oraz Swagger.
Comments