Phenquestions
Verze TL; DR
V jednom z předchozích příspěvků jsme stručně probrali, jaké to je používat GitHub API v3. Tato verze je navržena tak, aby mohla být propojena jako jakékoli jiné rozhraní REST API. Existují koncové body pro každý prostředek, ke kterému potřebujete získat přístup a / nebo jej upravit. Existují koncové body pro každého uživatele, každou organizaci, každé úložiště atd. Například každý uživatel má svůj koncový bod API na https: // api.github.com / uživatelé /
GitHub API v4 na druhé straně používá GraphQL, kde QL znamená Query Language. GraphQL je nový způsob návrhu vašich API. Stejně jako existuje mnoho webových služeb nabízených jako REST API, nejen ty, které nabízí GitHub, existuje mnoho webových služeb, které vám umožňují rozhraní s nimi prostřednictvím GraphQL.
Nejvýraznějším rozdílem, který si všimnete mezi GraphQL a REST API, je to, že GraphQL dokáže pracovat s jediným koncovým bodem API. V případě GitHub API v4 je tento koncový bod https: // api.github.com / graphql a to je vše. Nemusíte si dělat starosti s připojováním dlouhých řetězců na konec kořenového URI nebo zadáním parametru řetězce dotazu pro další informace. Jednoduše pošlete argument jako JSON do tohoto API a budete žádat pouze o věci, které potřebujete, a získáte zpět užitečné zatížení JSON se stejnými informacemi, jaké jste požadovali. Nemusíte se vypořádat s filtrováním nežádoucích informací nebo trpíte režií výkonu kvůli velkým odezvám.
Co je to REST API?
REST znamená Reprezentativní přenos stavu a API znamená Application Programming Interface. REST API nebo „RESTful“ API se stalo základní filozofií designu za nejmodernějšími aplikacemi klient-server. Myšlenka vychází z potřeby oddělit různé komponenty aplikace, jako je uživatelské rozhraní na straně klienta a logika na straně serveru.
Takže relace mezi klientem a serverem je obvykle bez státní příslušnosti. Po načtení webové stránky a souvisejících skriptů s nimi můžete pokračovat v interakci a při provádění akce (například stisknutí tlačítka pro odeslání) se odešle požadavek na odeslání spolu se všemi kontextovými informacemi, které webový server potřebuje ke zpracování tohoto požadavku ( jako uživatelské jméno, tokeny atd.). Aplikace přechází z jednoho stavu do druhého, ale bez neustálé potřeby připojení mezi klientem a serverem.
REST definuje sadu omezení mezi klientem a serverem a ke komunikaci může dojít pouze za těchto omezení. Například REST over HTTP obvykle používá model CRUD, což je zkratka pro Create, Read, Update and Delete a metody HTTP jako POST, GET, PUT a DELETE vám pomohou provádět tyto operace a tyto operace samostatně. Staré techniky narušení, jako jsou injekce SQL, nejsou možné u něčeho, jako je pečlivě napsané rozhraní REST API (i když je to REST, není všelékem zabezpečení).
Pomáhá také vývojářům uživatelského rozhraní docela dost! Protože vše, co obdržíte z požadavku HTTP, je typický proud textu (někdy formátovaný jako JSON), můžete snadno implementovat webovou stránku pro prohlížeče nebo aplikaci (ve vašem preferovaném jazyce) bez obav o architekturu na straně serveru. Přečtete si dokumentaci API pro služby jako Reddit, Twitter nebo Facebook a můžete pro ně nebo klienty třetích stran psát rozšíření v jazyce, který si vyberete, protože máte zaručeno, že chování API bude stále stejné.
Naopak serveru je jedno, zda je front-end napsán v Go, Ruby nebo Pythonu. Ať už se jedná o prohlížeč, aplikaci nebo rozhraní příkazového řádku. Prostě „vidí“ požadavek a odpovídajícím způsobem odpoví.
Co je GraphQL?
Stejně jako u čehokoli ve světě počítačů se rozhraní REST API zvětšovala a komplexovala a zároveň je lidé chtěli implementovat a spotřebovat rychlejším a jednodušším způsobem. To je důvod, proč Facebook přišel s myšlenkou GraphQL a později ji otevřel. QL v GraphQL znamená Query Language.
GraphQL umožňuje klientům vytvářet velmi specifické požadavky API, místo toho, aby uskutečňovali rigidní volání API s předdefinovanými parametry a odpověďmi. Je to mnohem jednodušší, protože server poté odpoví přesně takovými daty, o která jste jej požádali, a to bez přebytku.
Podívejte se na tento požadavek REST a jeho odpovídající odpověď. Tento požadavek je určen k zobrazení pouze veřejného biografického obsahu uživatele.
Žádost: ZÍSKEJTE https: // api.github.com / uživatelé /Odezva:
"login": "octocat",
"id": 583231,
"node_id": "MDQ6VXNlcjU4MzIzMQ ==",
"avatar_url": "https: // avatars3.githubusercontent.com / u / 583231?v = 4 ",
"gravatar_id": "",
"url": "https: // api.github.com / users / octocat ",
"html_url": "https: // github.com / octocat ",
"followers_url": "https: // api.github.com / users / octocat / followers ",
"following_url": "https: // api.github.com / users / octocat / following / other_user ",
"gists_url": "https: // api.github.com / users / octocat / gists / gist_id ",
"starred_url": "https: // api.github.com / users / octocat / starred / owner / repo ",
"subscriptions_url": "https: // api.github.com / users / octocat / předplatné ",
"organization_url": "https: // api.github.com / users / octocat / orgs ",
"repos_url": "https: // api.github.com / users / octocat / repos ",
"events_url": "https: // api.github.com / users / octocat / events / privacy ",
"receive_events_url": "https: // api.github.com / users / octocat / receive_events ",
"type": "Uživatel",
"site_admin": false,
"name": "Octocat",
"company": "GitHub",
"blog": "http: // www.github.com / blog ",
"location": "San Francisco",
"email": null,
"hireable": null,
"bio": null,
"public_repos": 8,
"public_gists": 8,
"následovníci": 2455,
„následující“: 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Použil jsem uživatelské jméno octocat, ale můžete ho nahradit uživatelským jménem podle vašeho výběru a použít cURL k provedení tohoto požadavku v příkazovém řádku nebo Postman, pokud požadujete grafické uživatelské rozhraní. I když byl požadavek jednoduchý, zamyslete se nad všemi dalšími informacemi, které z této odpovědi dostáváte. Pokud byste měli zpracovávat data od milionu takových uživatelů a odfiltrovat všechna zbytečná data pomocí, pak to není efektivní. Plýtváte šířkou pásma, pamětí a výpočty při získávání, ukládání a filtrování všech milionů dalších párů klíč – hodnota, které nikdy nebudete
Struktura odpovědi také není něco, co předem víte. Tato odpověď JSON je ekvivalentní objektu slovníku v Pythonu nebo objektu v JavaScriptu. Ostatní koncové body budou reagovat objekty JSON, které mohou být složeny z vnořených objektů, vnořeného seznamu v objektu nebo libovolné kombinace datových typů JSON, a pro získání podrobností budete muset odkázat na dokumentaci. Když zpracováváte požadavek, musíte si být vědomi tohoto formátu, který se mění z koncového bodu na koncový bod.
GraphQL se při provádění operací CRUD na serveru nespoléhá na slovesa HTTP jako POST, GET, PUT a DELETE. Místo toho existuje pouze jeden typ typu požadavku HTTP a endopint pro všechny operace související s CRUD. V případě GitHub se jedná o požadavky typu POST pouze s jedním koncovým bodem https: // api.github.com / graphql
Jelikož jde o požadavek POST, může s sebou nést tělo textu jako JSON, jehož prostřednictvím budou naše operace GraphQL. Tyto operace mohou být typea dotaz pokud chce jen přečíst nějaké informace, nebo to může být mutace v případě, že je třeba data upravit.
Chcete-li volat GraphQL API, můžete použít průzkumník GraphQL GitHubu. Podívejte se na tento GraphQL dotaz načíst stejný druh dat (veřejné biografie uživatele), jak jsme to udělali výše pomocí REST.
Žádost: POST https: // api.github.com / graphqldotaz
uživatel (přihlášení: "ranvo")
bio
Odezva:
"data":
"user":
"bio": "Milovníci techniky a vědy. Jsem z nejrůznějších nesouvisejících věcí
servery kvantové fyzice.\ r \ nPříležitostně píšu blogové příspěvky na výše uvedené zájmy."
Jak vidíte, odpověď se skládá pouze z toho, o co jste žádali, to je životopis uživatele. Konkrétního uživatele vyberete předáním uživatelského jména (v mém případě je ranvo) a poté požádáte o hodnotu atributu daného uživatele, v tomto případě tento atribut je bio. Server API vyhledá přesné konkrétní informace a odpoví na ně a na nic jiného.
Na druhou stranu GraphQL vám také umožní udělat jeden požadavek a extrahovat informace, které by vám vzaly více požadavků v tradičním REST API. Připomeňme, že všechny požadavky GraphQL jsou odesílány pouze jednomu koncovému bodu API. Vezměte si například případ použití, kdy potřebujete požádat server API GitHub o životopis uživatele a jeden z jeho klíčů SSH. Vyžadovalo by to dvě GET žádosti.
REST požadavky: ZÍSKEJTE https: // api.github.com /ZÍSKAT https: // api.github.com /
Požadavek GraphQL: POST https: // api.github.com / graphql /
dotaz
uživatel (přihlášení: "ranvo")
bio
publicKeys (poslední: 1)
hrany
uzel
klíč
Odpověď GraphQL:
"data":
"user":
"bio": "Milovníci techniky a vědy. Jsem z nejrůznějších nesouvisejících věcí
servery kvantové fyzice.\ r \ nPříležitostně píšu blogové příspěvky na výše uvedené zájmy.",
"publicKeys":
"edge": [
"uzel":
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Existují vnořené objekty, ale pokud se podíváte na svůj požadavek, do značné míry odpovídají vašemu požadavku, abyste věděli a v určitém smyslu formovali strukturu odpovědi, kterou dostanete .
Závěr
GraphQL má vlastní křivku učení, která je velmi strmá nebo vůbec strmá podle toho, o koho se ptáte. Z objektivního hlediska vám mohu uvést následující fakta. Je flexibilní, jak jste viděli výše, je introspektivní - to znamená, že můžete dotazovat API GraphQL na samotné API. I když nebudete používat svůj server API pomocí něj, je pravděpodobné, že budete muset komunikovat s API, které umožňuje pouze GraphQL.
Zde se můžete dozvědět něco více o jeho technických aspektech a pokud chcete volat GraphQL API z vaší místní pracovní stanice, použijte Graphiql.
