Zewnętrzne żądanie API

Nie za dużo teorii?

Przełóżmy to na praktykę. Otwórzmy AppMaster, stwórzmy za jego pomocą żądanie API i lepiej zrozumiejmy jak to żądanie działa.

Tworzenie zewnętrznego żądania API

Żądania API tworzy się w sekcji "Business logic", w zakładce "External API Requests".

Nadszedł czas, aby kliknąć "+ New API Request"

Nazwa i opis mogą być ustawione na cokolwiek, są tylko na nasz prywatny użytek.

Zajmijmy się danymi, które naprawdę mają znaczenie.

Minimum wymagane do stworzenia żądania to określenie jego Metody i adresu (URL). Zacznijmy od tego ostatniego.

URL

URL - Uniform Resource Locator (jednolity lokalizator zasobów). Adres nadawany konkretnemu zasobowi w Internecie. Najbardziej znaną wersją takiego zasobu jest strona HTML - wpisujemy jej adres URL w pasku adresu przeglądarki i otwieramy pożądaną witrynę. Jednocześnie samym zasobem może być cokolwiek, zdjęcie, film, zbiór danych. Najważniejsze jest to, że ten zasób ma określony wskaźnik - adres URL, do którego można wysłać żądanie, aby uzyskać ten zasób.

Metody

Odwołując się do danych pod ich adresem, wskazujemy również metodę (można też powiedzieć typ) żądania, czyli wskazujemy, co właściwie trzeba z tymi danymi zrobić.

Gdy wysyłaliśmy żądania dotyczące zadania pierwszego modułu, otrzymaliśmy dane. W tym przypadku mamy do czynienia z metodą GET. Metoda ta jest najbardziej oczywistą metodą, a także jedyną wymaganą. Dlatego nawet jeśli nie określiliśmy jej wprost, to i tak domyślnie zakładano, że jest to GET.

Zobaczmy, jakie istnieją inne metody.

Sam standard HTTP nie ogranicza liczby metod, które można stosować. Jednocześnie, aby zachować kompatybilność, nadal używa się tylko niektórych, najbardziej standardowych metod. Istnieje 5 różnych metod, które mogą być używane w żądaniach AppMaster API.

GET. Z tym mamy już do czynienia. Metoda ta żąda udostępnienia zasobu, a także otrzymuje dane.

POST. Aby pobrać dane z jakiegoś miejsca, najpierw trzeba te dane tam umieścić. Metoda POST właśnie to robi. Wysyła dane do serwera, tworzy zasób.

PUT. Podobna do metody POST, ale jej zadaniem jest aktualizacja danych. Nie tworzy nowych danych, ale zastępuje istniejące, aktualizuje je.

DELETE. Jak sama nazwa wskazuje, usuwa dane.

PATCH. Metoda podobna do PUT, ale służy do częściowej aktualizacji danych, a nie ich całkowitego zastąpienia. Na przykład, używając metody PATCH, możesz zmienić tytuł artykułu lub zmienić wartość jakiegoś parametru.

Należy wziąć pod uwagę fakt, że serwer wcale nie jest zobowiązany do wykonania dokładnie tego, co zostało określone w metodzie. Możemy wysłać adres jakiejś strony metodą DELETE, ale nie oznacza to, że serwer rzeczywiście ją usunie. Ale, czysto teoretycznie, może to zrobić za pomocą polecenia GET. Albo nic nie zmieniać, ale jednocześnie wysyłać dane w odpowiedzi na POST. Tylko dlatego, że deweloper tak to skonfigurował.

W tym miejscu do gry wchodzi REST, który mówi, że czas uzgodnić przestrzeganie polecenia, zatrzymać bałagan i zrobić dokładnie to, co jest wskazane w metodzie. Przynajmniej to powinno być głównym zadaniem (choć niekoniecznie jedynym). Np. przekazując treść artykułu metodą GET, można jednocześnie zwiększyć o 1 licznik liczby jego odsłon.

Zorientowaliśmy się więc, gdzie znajdują się dane i co można z nimi zrobić. Idźmy dalej, zobaczmy, jakie inne składowe może mieć żądanie.

Parametry URL

URL Params. Są sytuacje, w których znamy tylko część adresu URL. Przykładem mogą być artykuły na stronie Appmaster.io. Adres startowy dla wszystkich artykułów jest taki sam - https://appmaster.io/blog/. Ale potem każdy artykuł ma swój własny tytuł i odpowiednio swoją indywidualną część do dokładnego wskazania tego konkretnego artykułu.

W takiej sytuacji stosuje się URL Params. Od razu przepisujemy część ogólną, a resztę pozostawiamy do ustalenia w procesie. W rezultacie adres URL zapisany jest w postaci https://appmaster.io/blog/:id/.

Część znaną piszemy tak jak jest, a część zmienną umieszczamy po znaku ":". Nazwa tej zmiennej części (już bez ":") jest dodawana do listy parametrów. W tym przypadku może być kilka części zmiennych, a ich lokalizacja jest w dowolnym miejscu adresu URL.

Parametry zapytania

QueryParams. Pamiętasz jak w pierwszym module wysłaliśmy zapytanie do boredapi.com? I oprócz adresu były przepisane dodatkowe dane. To były właśnie Query Params.

Są one zapisane po adresie URL i oddzielone od niego znakiem "?". Podana jest nazwa parametru, znak "=" oraz wartość samego parametru. Jeśli używa się kilku parametrów jednocześnie, są one oddzielone znakiem "&".

Jednak podczas określania parametrów w AppMasterze nie musisz myśleć o regułach żądania. Wszystko zostanie odpowiednio sformatowane automatycznie. Wystarczy podać samą nazwę parametru i dodać go do listy.

Query Params są używane, gdy źródło danych jest takie samo, ale same dane mogą być różne. Na przykład Boredapi zawierało ogromną listę rzeczy do zrobienia. Ale interesowały nas tylko te, które są przeznaczone dla jednej osoby i to właśnie określiliśmy w parametrach żądania.

Innym przypadkiem użycia jest ograniczenie ilości danych. Na przykład moglibyśmy uzyskać dostęp do jakiejś listy, ale zażądać tylko pierwszych 5 wpisów z niej. Ta ilość również może być parametrem zapytania.

Inną opcją jest klucz dostępu. Być może korzystałeś z tej opcji w module 1 przy okazji odwoływania się do Alphavantage. Dane można było uzyskać dopiero po rejestracji i przesłaniu klucza osobistego w parametrach zapytania.

Zwróć uwagę na strony, które odwiedzasz w Internecie, prawdopodobnie w nich również znajdziesz różne parametry. Na przykład otwórz stronę z pogodą Ventusky.com, w parametrach zapytania wysyłane są wartości geograficzne szerokości i długości geograficznej.

Nagłówki

Nagłówki. Nagłówki żądania. Zazwyczaj nagłówki zawierają informacje serwisowe o żądaniu (meta-informacje). Nagłówki pozwalają serwerowi uzyskać więcej informacji o kliencie, który żąda danych. Nagłówki mogą zawierać informacje o tym, jaka przeglądarka jest używana, w jakim kodowaniu ma być odpowiedź, w jakim języku, dokładny czas żądania i inne. W przypadku dostępu do chronionych danych, nagłówki mogą zawierać klucz autoryzacji.

W większości przypadków nagłówki są opcjonalne. Już w pierwszym module wykonaliśmy żądanie, w którym nie określiliśmy żadnych nagłówków (choć nie oznacza to, że żądanie zostało faktycznie wysłane bez nich).

Body

Body. Ciało żądania. Żądania GET zazwyczaj obywają się bez niego, ale jeśli chcemy wysłać jakieś dane do serwera, wysyłamy żądanie POST lub PUT, to te dane umieszczamy w ciele żądania. Jednocześnie w ciele żądania można umieścić dane o dowolnej złożoności, na przykład wysłać plik wideo, i nie ograniczać się do jakiejś liczby czy ciągu tekstowego.