Wersja TL; DR

W jednym z poprzednich postów omówiliśmy w skrócie, jak to jest używać Github API V3. Ta wersja jest zaprojektowana tak, aby była połączona jak każdy inny interfejs API REST. Istnieją punkty końcowe dla każdego zasobu, do którego potrzebujesz uzyskać dostęp i/lub modyfikować. Istnieją punkty końcowe dla każdego użytkownika, każdej organizacji, każdego repozytorium i tak dalej. Na przykład każdy użytkownik ma swój punkt końcowy API na https: // API.github.com/ użytkownicy/ możesz spróbować zastąpić swoją nazwę użytkownika zamiast i wpisać adres URL w przeglądarce, aby zobaczyć, co odpowiada interfejs API.

Github API V4, z drugiej strony, używa GraphQL, w którym QL oznacza język zapytania. GraphQL to nowy sposób projektowania interfejsów API. Podobnie jak wiele usług internetowych oferowanych jako interfejsy API REST, a nie tylko te oferowane przez GitHub, istnieje wiele usług internetowych, które pozwalają z nimi interfejs za pośrednictwem GraphQL.

Najważniejszą różnicą, którą zauważysz między GraphQL i REST API, polega na tym, że GraphQL może działać z jednego punktu końcowego API. W przypadku GitHub API V4 ten punkt końcowy to https: // api.github.com/grafql i to wszystko. Nie musisz się martwić o dołączenie długich ciągów na końcu root adres URI lub dostarczyć parametr ciągu zapytań, aby uzyskać dodatkowe informacje. Po prostu wysyłasz argument podobny do JSON do tego interfejsu API, prosząc tylko o rzeczy, których potrzebujesz, a otrzymasz ładunek JSON z dokładnie taką samą informacją, o której prosiłeś. Nie musisz radzić sobie z filtrowaniem niechcianych informacji lub cierpieć z powodu kosztów wydajności z powodu dużych odpowiedzi.

Co to jest API REST?

Cóż, odpoczynek oznacza reprezentacyjne transfer stanu, a API oznacza interfejs programowania aplikacji. API REST lub „RESTful” API stał się podstawową filozofią projektową za większymi nowoczesnymi aplikacjami klientów-serwer. Pomysł wyłania się z potrzeby segregowania różnych komponentów aplikacji, takich jak interfejs użytkownika po stronie klienta i logika po stronie serwera.

Tak więc sesja między klientem a serwerem jest zazwyczaj bezstronna. Po załadowaniu strony internetowej i powiązanych skryptów możesz kontynuować interakcję z nimi, a po wykonaniu akcji (naciśnij przycisk Wyślij), wysyłane jest żądanie wysyłania wraz ze wszystkimi informacjami kontekstowymi, których serwer WWW musi przetworzyć to żądanie ( Jak nazwa użytkownika, tokeny itp.). Aplikacja przechodzi z jednego stanu do drugiego, ale bez ciągłej potrzeby połączenia między klientem a serwerem.

REST definiuje zestaw ograniczeń między klientem a serwerem, a komunikacja może się zdarzyć tylko w ramach tych ograniczeń. Na przykład odpoczynek na HTTP zwykle używa modelu CRUD, który oznacza tworzenie, czytanie, aktualizację i usuwanie i http, takie jak post, get, put i usuwanie pomocy w wykonywaniu tych operacji i samych tych operacji. Stare techniki włamań, takie jak zastrzyki SQL, nie są możliwe z czymś w rodzaju szczelnie napisanego interfejsu API REST (chociaż odpoczynek nie jest panaceum bezpieczeństwa).

Pomaga także twórcom interfejsu użytkownika w dużej mierze! Ponieważ wszystko, co otrzymujesz z żądania HTTP, jest typowym strumieniem tekstu (czasami sformatowanym jako JSON), możesz łatwo zaimplementować stronę internetową dla przeglądarek lub aplikacji (w preferowanym języku), nie martwiąc się o architekturę po stronie serwera. Czytasz dokumentację API dla usług takich jak Reddit, Twitter lub Facebook i możesz pisać rozszerzenia dla nich lub klientów innych firm w wybranym języku, ponieważ masz gwarancję, że zachowanie API będzie nadal takie samo.

I odwrotnie, serwer nie dba o to, czy front-end jest napisany w Go, Ruby czy Python. Czy jest to przeglądarka, aplikacja czy CLI. Po prostu „widzi” żądanie i odpowiednio odpowiada.

Co to jest GraphQl?

Podobnie jak w przypadku wszystkiego w świecie komputerów, REST API stały się większe i bardziej złożone, a jednocześnie ludzie chcieli je wdrożyć i konsumować szybszy i prostszy sposób. Właśnie dlatego Facebook wpadł na pomysł GraphQL, a później otwarty go pozyskał. QL w GraphQL oznacza język zapytania.

GraphQL pozwala klientom na bardzo specyficzne żądania interfejsu API, zamiast wykonywać sztywne wywołania interfejsu API z predefiniowanymi parametrami i odpowiedziami. Jest to znacznie prostsze, ponieważ serwer odpowiada dokładnie danymi, o które prosiłeś, bez nadwyżki.

Spójrz na to żądanie odpoczynku i odpowiedniej odpowiedzi. To żądanie ma wyświetlić tylko publiczną biografię użytkownika.

Żądanie: Pobierz https: // API.github.com/użytkownicy/
Odpowiedź:

„Login”: „Octocat”,
„ID”: 583231,
„Node_id”: „MDQ6VXNLCJU4MZIZMQ ==”,
„Avatar_url”: „https: // awatars3.Githubusercontent.com/u/583231?v = 4 ",
„Gravatar_id”: „”,
„URL”: „https: // API.github.COM/Użytkownicy/Octocat ",
„html_url”: „https: // github.com/oktocat ",
„Fouringers_url”: „https: // API.github.COM/Użytkownicy/Octocat/obserwatorzy ",
„persone_url”: „https: // api.github.com/users/oktoCat/następujący /inni_user ",
„gists_url”: „https: // api.github.com/Users/oktocat/gists /gist_id ”,
„Starred_url”: „https: // api.github.com/Users/Octocat/Gwiazdy /właściciel /repo ",
„subskrypcja_url”: „https: // API.github.COM/Użytkownicy/oktocat/subskrypcje ",
„Organizations_Url”: „https: // API.github.COM/Użytkownicy/Octocat/Orgs ",
„Repos_Url”: „https: // api.github.COM/Użytkownicy/Octocat/Repos ",
„Events_Url”: „https: // API.github.com/Users/oktocat/events /privacy ",
„Otrzymane_events_url”: „https: // api.github.com/Users/Octocat/otrzymane_events ",
„Typ”: „Użytkownik”,
„Site_Admin”: False,
„Nazwa”: „Octocat”,
„Firma”: „Github”,
„Blog”: „http: // www.github.com/blog ",
„Lokalizacja”: „San Francisco”,
„E -mail”: Null,
„Hirible”: null,
„Bio”: Null,
„public_repos”: 8,
„public_gists”: 8,
„Zwolennicy”: 2455,
„Obserwuj”: 9,
„Created_at”: „2011-01-25T18: 44: 36Z”,
„Update_at”: „2018-11-22T16: 00: 23Z”

Użyłem nazwy użytkownika Octocat, ale możesz go zastąpić wybraną nazwą użytkownika i użyć curl, aby złożyć to żądanie w wierszu poleceń lub listonosze, jeśli potrzebujesz GUI. Chociaż prośba była prosta, pomyśl o wszystkich dodatkowych informacjach, które otrzymujesz z tej odpowiedzi. Jeśli przetworzysz dane od miliona takich użytkowników i odfiltrowałeś wszystkie niepotrzebne dane, wówczas nie jest to wydajne. Marnujesz przepustowość, pamięć i obliczasz przy zdobywaniu, przechowywaniu i filtrowaniu wszystkich milionów dodatkowych par kluczowych, których nigdy nie będziesz

Także struktura odpowiedzi nie jest czymś, co znasz wcześniej. Ta odpowiedź JSON jest równoważna z obiektem słownikowym w Pythonie lub obiektem w JavaScript. Inne punkty końcowe odpowiedzą obiektami JSON, które mogą składać się z zagnieżdżonych obiektów, zagnieżdżonej listy w obiekcie lub dowolnej dowolnej kombinacji typów danych JSON, i musisz odwołać dokumentację, aby uzyskać szczegółowe informacje. Podczas przetwarzania żądania musisz być świadomy tego formatu, który zmienia się z punktu końcowego na punkt końcowy.

GraphQL nie opiera się na czasownikach HTTP, takich jak post, Get, Put i Usuń, aby wykonywać operacje CRUD na serwerze. Zamiast tego istnieje tylko jeden typ typu żądania HTTP i endopint dla wszystkich operacji związanych z CRUD. W przypadku github obejmuje to żądania postu typu z tylko jednym punktem końcowym https: // api.github.com/ghantql

Będąc żądaniem pocztowym, które może zabrać ze sobą JSON podobny do tekstu, przez który będzie naszymi operacjami GraphQL. Te operacje mogą być z typu zapytanie Jeśli wszystko, co chce zrobić, to przeczytać informacje lub może to być mutacja W przypadku zmodyfikowania danych.

Aby wykonać wywołania API GHAGHQL, możesz użyć Github Explorer. Spójrz na ten GraphQL zapytanie Aby pobrać ten sam rodzaj danych (publiczna biografia użytkownika), co powyżej, za pomocą odpoczynku.

Żądanie: Opublikuj https: // API.github.com/ghantql
zapytanie
użytkownik (login: „ranvo”)
BIO


Odpowiedź:

"dane":
„Użytkownik”:
„Bio”: „Entuzjaści technologii i nauki. Jestem w różnych niezwiązanych rzeczach
serwery do fizyki kwantowej.\ r \ Noccasionally piszę posty na blogu na temat powyższych zainteresowań."

Jak widać, odpowiedź składa się tylko z tego, o co prosiłeś, to biografia użytkownika. Wybierasz konkretnego użytkownika, przekazując nazwę użytkownika (w moim przypadku jest to Ranvo), a następnie prosisz o wartość atrybutu tego użytkownika, w tym przypadku atrybut ten jest BIO. Serwer API szuka dokładnych konkretnych informacji i nie odpowiada na to i nic więcej.

Z drugiej strony GraphQL pozwala również złożyć jedno żądanie i wyodrębnić informacje, które przyjęłyby wiele żądań w tradycyjnym interfejsie API REST. Przypomnij sobie, że wszystkie żądania GraphQL są składane tylko do jednego punktu końcowego API. Weźmy na przykład przypadek użycia, w którym musisz zapytać serwer API GITHUB o bio użytkownika i jeden z jego kluczy SSH. Wymagałoby to dwóch rezerwatów.

Żądania REST: Pobierz https: // API.github.com//
Pobierz https: // API.github.com//Klucze
Żądanie GraphQL: Opublikuj https: // API.github.com/graftql/
zapytanie
użytkownik (login: „ranvo”)
BIO
publicKeys (last: 1)
krawędzie
węzeł
klucz





Odpowiedź GraphQL:

"dane":
„Użytkownik”:
„Bio”: „Entuzjaści technologii i nauki. Jestem w różnych niezwiązanych rzeczach
serwery do fizyki kwantowej.\ r \ Noccasionally piszę posty na blogu na temat powyższych zainteresowań.",
„publicKeys”:
„Krawędzie”: [

„węzeł”:
„Key”: „SSH-ED25519 AAAAC3NZAC1lZDI1NTE5AAAIH31MVJRYDZEH8OD8JVAFPRUIGL65SWILYKPEGBUNGOT”


]

Istnieje zagnieżdżony obiekt, ale jeśli spojrzysz na Twoją prośbę, prawie pasują one do Twojej prośby, abyś mógł wiedzieć, a w pewnym sensie kształtuj strukturę otrzymanej odpowiedzi .

Wniosek

Graphql ma własną krzywą uczenia się, która jest bardzo stroma lub wcale stroma w zależności od tego, kogo pytasz. Z obiektywnego punktu widzenia mogę położyć dla ciebie następujące fakty. Jest elastyczny, jak widziałeś powyżej, jest introspektywna - to znaczy, że możesz zapytać API GraphQL o samym interfejsie API. Nawet jeśli nie zamierzasz używać go serwera API, istnieje szansa.

Możesz dowiedzieć się nieco więcej o jego technikach tutaj, a jeśli chcesz wykonać połączenia API GraphQL od lokalnej stacji roboczej, a następnie użyć GraphiQL.