Zrozumienie i korzystanie z interfejsów API REST

Istnieje duże prawdopodobieństwo, że natknąłeś się na termin „REST API”, jeśli myślałeś o pobraniu danych z innego źródła w Internecie, takiego jak Twitter lub Github. Ale czym jest REST API? Co może dla ciebie zrobić? Jak tego używasz?

W tym artykule dowiesz się wszystkiego, co musisz wiedzieć o REST API, aby móc czytać dokumentację API i efektywnie z nich korzystać.

Co to jest REST API

Załóżmy, że próbujesz znaleźć filmy o Batmanie na Youtube. Otwierasz YouTube, wpisujesz „Batman” w polu wyszukiwania, wciskasz Enter i widzisz listę filmów o Batmanie. W podobny sposób działa REST API. Szukasz czegoś, a otrzymasz listę wyników z powrotem z usługi, z której prosisz.

API to interfejs programowania aplikacji. Jest to zestaw reguł, które pozwalają programom komunikować się ze sobą. Deweloper tworzy API na serwerze i pozwala klientowi rozmawiać z nim.

REST określa, jak wygląda API. Oznacza „Reprezentacyjny transfer państwowy”. Jest to zbiór zasad, których przestrzegają programiści, tworząc swoje API. Jedna z tych reguł mówi, że powinieneś być w stanie uzyskać część danych (nazywaną zasobem), gdy łączysz się z określonym adresem URL.

Każdy adres URL jest nazywany żądaniem , a dane odesłane do użytkownika nazywane są odpowiedzią .

Anatomia prośby

Ważne jest, aby wiedzieć, że prośba składa się z czterech rzeczy:

1. Punkt końcowy
2. Metoda
3. Nagłówki
4. Dane (lub ciało)

Punkt końcowy (lub trasa) to żądany adres URL. Wynika z tej struktury:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

Główny punkt końcowy to punkt początkowy interfejsu API, z którego żądasz. Główny punkt końcowy interfejsu API Github to https://api.github.com , a główny punkt końcowy API Twittera to https://api.twitter.com .

Ścieżka określa zasób, o który prosisz. Pomyśl o tym jak o automatycznej sekretarce, która prosi o naciśnięcie 1 dla usługi, naciśnij 2 dla innej usługi, 3 dla jeszcze innej usługi i tak dalej.

Możesz uzyskać dostęp do ścieżek, tak jak łączysz się z częściami witryny. Na przykład, aby uzyskać listę wszystkich postów oznaczonych jako „JavaScript” w Smashing Magazine, przejdź do https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ to główny punkt końcowy, a /tag/javascript to ścieżka.

Aby zrozumieć, jakie ścieżki są dla Ciebie dostępne, musisz przejrzeć dokumentację API. Załóżmy na przykład, że chcesz uzyskać listę repozytoriów określonego użytkownika za pośrednictwem interfejsu API Github. Dokumenty zalecają skorzystanie w tym celu z następującej ścieżki:

 /users/:username/repos

Wszelkie dwukropki ( : ) na ścieżce oznaczają zmienną. Należy zastąpić te wartości rzeczywistymi wartościami w momencie wysłania żądania. W takim przypadku należy zastąpić :username rzeczywistą nazwą użytkownika, którego szukasz. Jeśli szukam swojego konta Github, zamienię :username na zellwk .

Punktem końcowym do pobrania listy moich repozytoriów na Github jest:

 https://api.github.com/users/zellwk/repos

Ostatnią częścią punktu końcowego są parametry zapytania . Technicznie rzecz biorąc, parametry zapytania nie są częścią architektury REST, ale zobaczysz, że używa ich wiele interfejsów API. Tak więc, aby pomóc Ci w pełni zrozumieć, jak czytać i używać API, będziemy również o nich mówić. Parametry zapytania umożliwiają modyfikowanie żądania za pomocą par klucz-wartość. Zawsze zaczynają się od znaku zapytania ( ? ). Każda para parametrów jest następnie oddzielona znakiem ampersand ( & ), w ten sposób:

 ?query1=value1&query2=value2

Kiedy próbujesz uzyskać listę repozytoriów użytkownika na Github, dodajesz trzy możliwe parametry do swojego żądania, aby zmodyfikować otrzymane wyniki:

Jeśli chcesz otrzymać listę repozytoriów, do których ostatnio wypchnąłem, możesz ustawić sort na push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Skąd wiesz, czy ten punkt końcowy działa? Cóż, czas spróbować!

Testowanie punktów końcowych za pomocą curl

Możesz wysłać zapytanie w dowolnym języku programowania. Użytkownicy JavaScript mogą używać metod takich jak Fetch API i metoda Ajax jQuery; Użytkownicy Rubiego mogą używać klasy Ruby's Net::HTTP, użytkownicy Pythona mogą używać Python Requests; i tak dalej.

W tym artykule użyjemy narzędzia wiersza poleceń o nazwie cURL. Używamy cURL, ponieważ dokumentacja API jest zwykle pisana w odniesieniu do cURL. Jeśli rozumiesz, jak używać cURL, nie będziesz miał problemów ze zrozumieniem dokumentacji API. Następnie możesz łatwo wykonywać żądania w preferowanym języku.

Zanim przejdziesz dalej, upewnij się, że masz zainstalowany cURL na swoim komputerze. Otwórz terminal i wpisz curl -version . To polecenie sprawdza wersję cURL, którą zainstalowałeś w swoim systemie.

 curl --version

Jeśli nie masz zainstalowanego cURL, otrzymasz błąd „nie znaleziono polecenia”. Jeśli pojawi się ten błąd, będziesz musiał zainstalować curl przed przejściem dalej.

Aby użyć cURL, wpisz curl , a następnie punkt końcowy, o który prosisz. Na przykład, aby uzyskać główny punkt końcowy Github, wpisz następujące polecenie:

 curl https://api.github.com

Po naciśnięciu Enter powinieneś otrzymać odpowiedź z Github, która wygląda tak:

Aby uzyskać listę repozytoriów użytkownika, modyfikuj punkt końcowy do właściwej ścieżki, tak jak omówiliśmy powyżej. Aby uzyskać listę moich repozytoriów, możesz użyć tego polecenia:

 curl https://api.github.com/users/zellwk/repos

Jeśli chcesz dołączyć parametry zapytania do \ , upewnij się, że przed znakiem ? i = znaki. To dlatego, że ? i = to znaki specjalne w linii poleceń. Musisz użyć \ przed nimi, aby linia poleceń zinterpretowała je jako normalne znaki:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Spróbuj użyć jednego z poleceń i wykonaj żądanie! Otrzymasz podobną odpowiedź do tego, co widziałeś z root-endpontem Github (ale z dużo większą ilością danych).

JSON

JSON (JavaScript Object Notation) wspólny format wysyłania i żądania danych za pośrednictwem interfejsu API REST. Odpowiedź, którą Github wysyła do Ciebie, jest również sformatowana jako JSON.

Obiekt JSON wygląda jak obiekt JavaScript. W JSON każda właściwość i wartość muszą być otoczone podwójnymi cudzysłowami, na przykład:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

Powrót do anatomii prośby

Dowiedziałeś się, że prośba składa się z czterech części.

1. Punkt końcowy
2. Metoda
3. Nagłówki
4. Dane (lub ciało)

Przejdźmy przez resztę tego, co składa się na prośbę.

Metoda

Metoda jest typem żądania wysyłanego do serwera. Możesz wybrać spośród tych pięciu typów poniżej:

• GET
• POST
• PUT
• PATCH
• DELETE

Te metody nadają znaczenie żądaniu, które składasz. Służą do wykonywania czterech możliwych akcji: Create , Read , Update i Delete (CRUD).

Interfejs API informuje, jakiej metody żądania użyć w każdym żądaniu. Na przykład, aby uzyskać listę repozytoriów użytkownika, potrzebujesz żądania GET :

Żądanie GET jest wymagane, aby uzyskać od użytkownika listę repozytoriów. Aby utworzyć nowe repozytorium Github, potrzebujesz POST :

Możesz ustawić metodę żądania w cURL, pisząc -X lub --request , a następnie metodę żądania. Poniższe polecenie próbuje utworzyć repozytorium za pomocą cURL:

 curl -X POST https://api.github.com/user/repos

Spróbuj uruchomić to żądanie. Otrzymasz odpowiedź z informacją, że wymagane jest uwierzytelnienie. (Więcej o uwierzytelnianiu później).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Nagłówki

Nagłówki służą do przekazywania informacji zarówno klientowi, jak i serwerowi. Może być używany do wielu celów, takich jak uwierzytelnianie i dostarczanie informacji o zawartości treści. Listę prawidłowych nagłówków można znaleźć w MDN's HTTP Headers Reference.

Nagłówki HTTP to pary właściwość-wartość oddzielone dwukropkiem. Poniższy przykład pokazuje nagłówek, który informuje serwer, aby oczekiwał zawartości JSON.

 "Content-Type: application/json". Missing the opening ".

Możesz wysyłać nagłówki HTTP z curl za pomocą opcji -H lub --header . Aby wysłać powyższy nagłówek do API Github, użyj tego polecenia:

 curl -H "Content-Type: application/json" https://api.github.com

(Uwaga: nagłówek Content-Type nie jest wymagany do działania API Github. Jest to tylko przykład ilustrujący, jak używać nagłówka z cURL).

Aby wyświetlić wysłane nagłówki, możesz użyć opcji -v lub --verbose podczas wysyłania żądania, na przykład:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Tutaj * odnosi się do dodatkowych informacji dostarczonych przez cURL. > odnosi się do nagłówków żądań, a < do nagłówków odpowiedzi.

Dane (lub „Ciało”)

Dane (nazywane czasami „treścią” lub „wiadomością”) zawierają informacje, które chcesz przesłać na serwer. Ta opcja jest używana tylko w przypadku żądań POST , PUT , PATCH lub DELETE .

Aby wysłać dane przez cURL, możesz użyć opcji -d lub --data :

 curl -X POST <URL> -d property1=value1

Aby wysłać wiele pól danych, możesz utworzyć wiele opcji -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Jeśli ma to sens, możesz podzielić swoje żądanie na wiele wierszy \ , aby ułatwić czytanie:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Jeśli wiesz, jak uruchomić serwer, możesz stworzyć API i przetestować własne dane. Jeśli nie wiesz, ale masz dość odwagi, aby spróbować, możesz śledzić ten artykuł, aby dowiedzieć się, jak stworzyć serwer z Node, Express i MongoDB

Jeśli nie chcesz rozkręcać serwera, możesz przejść do Requestbin.com ( to nic nie kosztuje! ) i kliknąć „utwórz punkt końcowy”. Otrzymasz adres URL, którego możesz użyć do testowania żądań, taki jak https://requestb.in/1ix963n1 pokazany na poniższym obrazku.

Upewnij się, że utworzyłeś własny pojemnik na żądania, jeśli chcesz przetestować swoje żądanie. Pojemniki na żądania pozostają otwarte tylko przez 48 godzin po ich utworzeniu. Zanim przeczytasz ten artykuł, kosz, który stworzyłem powyżej, już dawno zniknie.

Teraz spróbuj wysłać trochę danych do kosza żądań, a następnie odśwież stronę internetową swojego kosza. Zobaczysz niektóre dane, takie jak:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Domyślnie cURL wysyła dane tak, jakby były wysyłane przez „pola formularza” na stronie. Jeśli chcesz wysyłać dane JSON, musisz ustawić Content-Type na application/json i sformatować dane jako obiekt JSON w następujący sposób:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

I to jest (prawie!) wszystko, co musisz wiedzieć o strukturze wniosku.

Teraz pamiętasz, gdy próbowałeś wysłać żądanie POST przez API Github, otrzymałeś komunikat „Wymaga uwierzytelnienia”? Cóż, to dlatego, że nie masz uprawnień do wykonania POST !

Uwierzytelnianie

Nie pozwoliłbyś nikomu na dostęp do Twojego konta bankowego bez Twojej zgody, prawda? Zgodnie z tym samym tokiem myślenia programiści wprowadzają środki, aby zapewnić, że wykonasz działania tylko wtedy, gdy masz do tego upoważnienie. Uniemożliwia to innym podszywanie się pod Ciebie.

Ponieważ POST , PUT , PATCH i DELETE zmieniają bazę danych, programiści prawie zawsze umieszczają je za ścianą uwierzytelniającą. W niektórych przypadkach żądanie GET wymaga również uwierzytelnienia (na przykład podczas uzyskiwania dostępu do konta bankowego w celu sprawdzenia aktualnego salda).

W sieci istnieją dwa główne sposoby uwierzytelnienia się:

1. Z nazwą użytkownika i hasłem (zwane również uwierzytelnianiem podstawowym)
2. Z tajnym tokenem

Tajna metoda tokena obejmuje oAuth, która umożliwia uwierzytelnianie się w sieciach społecznościowych, takich jak Github, Google, Twitter, Facebook itp.

W tym artykule dowiesz się, jak używać uwierzytelniania podstawowego tylko z nazwą użytkownika i hasłem. Jeśli interesuje Cię uwierzytelnianie za pomocą oAuth, proponuję przeczytać „Co musisz wiedzieć o OAuth2 i logowaniu za pomocą Facebooka” autorstwa Zacka Grossbarta.

Aby przeprowadzić podstawowe uwierzytelnianie za pomocą cURL, możesz użyć opcji -u , a następnie swojej nazwy użytkownika i hasła, w następujący sposób:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Spróbuj uwierzytelnić się za pomocą swojej nazwy użytkownika i hasła w powyższym żądaniu. Po pomyślnym uwierzytelnieniu zobaczysz, że odpowiedź zmieni się z „Wymaga uwierzytelniania” na „Problemy z analizą JSON”.

Dzieje się tak, ponieważ nie musisz jeszcze podać żadnych danych (które są wymagane przez wszystkie POST , PUT , PATCH i DELETE ) na serwer.

Mając wiedzę, której się do tej pory nauczyłeś, powinieneś być w stanie edytować powyższy kod, aby utworzyć repozytorium Github za pośrednictwem swojego cURL. Zostawię cię, abyś sam spróbował!

Porozmawiajmy teraz o kodach stanu HTTP i komunikatach o błędach.

Kody stanu HTTP i komunikaty o błędach

Niektóre z otrzymanych wcześniej wiadomości, np. „Wymaga uwierzytelnienia” i „Problemy z analizą JSON”, to komunikaty o błędach. Pojawiają się tylko wtedy, gdy coś jest nie tak z Twoją prośbą. Kody stanu HTTP pozwalają szybko określić stan odpowiedzi. Zakres od 100+ do 500+. Ogólnie rzecz biorąc, liczby są zgodne z następującymi zasadami:

1. 200+ oznacza, że ​​żądanie powiodło się .
2. 300+ oznacza, że ​​żądanie jest przekierowywane na inny adres URL
3. 400+ oznacza, że ​​wystąpił błąd pochodzący od klienta
4. 500+ oznacza, że ​​wystąpił błąd pochodzący z serwera

Możesz debugować stan odpowiedzi za pomocą opcji verbose ( -v lub --verbose ) lub opcji head ( -I lub --head ).

Na przykład, jeśli spróbujesz dodać -I do POST bez podania nazwy użytkownika i hasła, otrzymasz kod stanu 401 (Nieautoryzowany):

Jeśli żądanie jest nieprawidłowe, ponieważ dane są nieprawidłowe lub ich brakuje, zwykle otrzymujesz kod stanu 400 (złe żądanie).

Aby uzyskać więcej informacji o określonych kodach statusu HTTP, możesz zapoznać się z dokumentacją MDN HTTP Status Reference.

Wersje API

Deweloperzy od czasu do czasu aktualizują swoje interfejsy API. Czasami API może zmienić się tak bardzo, że deweloper decyduje się na aktualizację swojego API do innej wersji. Jeśli tak się stanie, a Twoja aplikacja się zepsuje, jest to zwykle spowodowane tym, że napisałeś kod dla starszego interfejsu API, ale Twoje żądanie wskazuje na nowszy interfejs API.

Możesz poprosić o konkretną wersję API na dwa sposoby. Wybór sposobu zależy od sposobu napisania interfejsu API.

Te dwa sposoby to:

1. Bezpośrednio w punkcie końcowym
2. W nagłówku żądania

Na przykład Twitter używa pierwszej metody. W chwili pisania tego tekstu interfejs API Twittera jest w wersji 1.1, co widać po jego punkcie końcowym:

 https://api.twitter.com/1.1/account/settings.json

Z drugiej strony Github używa drugiej metody. W chwili pisania tego tekstu interfejs API Github jest w wersji 3 i możesz określić wersję za pomocą nagłówka Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Zawijanie

W tym artykule dowiedziałeś się, czym jest REST API i jak używać cURL do wykonywania żądania za pomocą metod GET , POST , PUT , PATCH i DELETE . Ponadto dowiedziałeś się również, jak uwierzytelniać swoje żądania za pomocą opcji -u i co oznaczają statusy HTTP.

Mam nadzieję, że ten artykuł pomógł Ci wystarczająco dużo dowiedzieć się o interfejsach API REST i możesz z nich płynnie korzystać podczas tworzenia aplikacji. Zapraszam do odwiedzenia mojego bloga lub pozostawienia komentarzy poniżej, jeśli masz jakieś pytania.