Phenquestions
Verzia TL; DR
V jednom z predchádzajúcich príspevkov sme v krátkosti diskutovali o tom, aké to je používať GitHub API v3. Táto verzia je navrhnutá na prepojenie ako každé iné rozhranie REST API. Pre každý zdroj, ku ktorému potrebujete prístup a / alebo upraviť, existujú koncové body. Existujú koncové body pre každého používateľa, každú organizáciu, každé úložisko atď. Napríklad každý používateľ má svoj koncový bod API na https: // api.github.com / users /
GitHub API v4, na druhej strane, používa GraphQL, kde QL znamená Query Language. GraphQL je nový spôsob navrhovania vašich rozhraní API. Rovnako ako existuje veľa webových služieb ponúkaných ako REST API, nielen tie, ktoré ponúka GitHub, existuje veľa webových služieb, ktoré vám umožňujú rozhranie s nimi prostredníctvom GraphQL.
Najvýraznejším rozdielom, ktorý si všimnete medzi GraphQL a REST API, je to, že GraphQL dokáže pracovať s jedným koncovým bodom API. V prípade GitHub API v4 je týmto koncovým bodom https: // api.github.com / graphql a to je všetko. Nemusíte sa starať o pridanie dlhých reťazcov na koniec koreňového identifikátora URI alebo zadať parameter reťazca dotazu, aby ste získali ďalšie informácie. Jednoducho pošlete argument ako JSON do tohto API a požiadate iba o veci, ktoré potrebujete, a získate späť užitočné zaťaženie JSON s presne rovnakými informáciami, aké ste požadovali. Nemusíte riešiť filtrovanie nežiaducich informácií alebo trpieť réžiou výkonu kvôli veľkým odpovediam.
Čo je to REST API?
REST je skratka pre Representational State Transfer a API pre skratku Application Programming Interface. REST API alebo „RESTful“ API sa stalo hlavnou filozofiou dizajnu, ktorá stojí za najmodernejšími aplikáciami typu klient-server. Myšlienka vychádza z potreby oddeliť rôzne komponenty aplikácie, ako sú používateľské rozhranie na strane klienta a logika na strane servera.
Takže relácia medzi klientom a serverom je zvyčajne bez štátnej príslušnosti. Po načítaní webovej stránky a súvisiacich skriptov s nimi môžete ďalej komunikovať a pri vykonávaní akcie (napríklad stlačenia tlačidla odoslania) sa odošle žiadosť o odoslanie spolu so všetkými kontextovými informáciami, ktoré webový server potrebuje na spracovanie tejto žiadosti ( ako používateľské meno, tokeny atď.). Aplikácia prechádza z jedného stavu do druhého, ale bez neustálej potreby spojenia medzi klientom a serverom.
REST definuje množinu obmedzení medzi klientom a serverom a komunikácia môže prebiehať iba za týchto obmedzení. Napríklad REST over HTTP zvyčajne používa model CRUD, čo je skratka pre Create, Read, Update and Delete a metódy HTTP ako POST, GET, PUT a DELETE vám pomôžu vykonávať tieto operácie a samotné tieto operácie. Staré techniky vniknutia, ako sú injekcie SQL, nie sú možné s niečím ako pevne napísaným rozhraním REST API (hoci je to REST, nie je to bezpečnostný všeliek).
Pomáha tiež dosť vývojárom používateľského rozhrania! Pretože všetko, čo dostanete od požiadavky HTTP, je typický prúd textu (niekedy vo formáte JSON), môžete ľahko implementovať webovú stránku pre prehliadače alebo aplikáciu (vo vašom preferovanom jazyku) bez obáv o architektúru na strane servera. Prečítajte si dokumentáciu API pre služby ako Reddit, Twitter alebo Facebook a môžete pre nich alebo klientov tretích strán písať rozšírenia v jazyku podľa vášho výberu, pretože máte zaručené, že chovanie API bude stále rovnaké.
Naopak, serveru je úplne jedno, či je front-end napísaný v jazykoch Go, Ruby alebo Python. Či už ide o prehliadač, aplikáciu alebo CLI. Iba „vidí“ požiadavku a primerane odpovie.
Čo je GraphQL?
Rovnako ako v čomkoľvek vo svete počítačov, rozhrania REST API sa zväčšovali a komplikovali a zároveň ich ľudia chceli implementovať a spotrebovať rýchlejšie a jednoduchšie. Preto Facebook prišiel s myšlienkou GraphQL a neskôr ju otvoril. QL v GraphQL znamená Query Language.
GraphQL umožňuje klientom zadávať veľmi špecifické požiadavky API, namiesto toho, aby uskutočňovali rigidné volania API s preddefinovanými parametrami a odpoveďami. Je to oveľa jednoduchšie, pretože server potom odpovie presnými údajmi, ktoré ste od nich požadovali, a to bez nadmerného množstva.
Zoznámte sa s touto požiadavkou REST a jej zodpovedajúcou odpoveďou. Táto žiadosť je určená na zobrazenie iba verejného biografie používateľa.
Žiadosť: ZÍSKAJTE https: // api.github.com / users /Odpoveď:
"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 / sledovatelia ",
"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 / predplatné ",
"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": "Používateľ",
"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,
„sledovatelia“: 2455,
„nasledujúci“: 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Použil som používateľské meno octocat, ale môžete ho nahradiť používateľským menom podľa vášho výberu a pomocou príkazu cURL zadať túto požiadavku v príkazovom riadku alebo poštárom, ak požadujete grafické používateľské rozhranie. Aj keď bola žiadosť jednoduchá, myslite na všetky ďalšie informácie, ktoré z tejto odpovede dostávate. Ak by ste mali spracovávať údaje od milióna takýchto používateľov a filtrovať pomocou nich všetky nepotrebné údaje, potom by to nebolo efektívne. Strácate šírku pásma, pamäť a výpočty pri získavaní, ukladaní a filtrovaní všetkých miliónov ďalších párov kľúč - hodnota, ktoré nikdy nebudete
Štruktúra odpovede tiež nie je niečo, čo vopred poznáte. Táto odpoveď JSON je ekvivalentná objektu slovníka v Pythone alebo objektu v JavaScripte. Ostatné koncové body budú odpovedať objektmi JSON, ktoré sa môžu skladať z vnorených objektov, vnoreného zoznamu v objekte alebo z ľubovoľnej kombinácie dátových typov JSON. Ak chcete získať špecifiká, budete si musieť prečítať dokumentáciu. Pri spracovávaní žiadosti musíte poznať tento formát, ktorý sa mení z koncového bodu na koncový bod.
GraphQL sa pri vykonávaní CRUD operácií na serveri nespolieha na slovesá HTTP ako POST, GET, PUT a DELETE. Namiesto toho existuje iba jeden typ typu požiadavky HTTP a endopint pre všetky operácie spojené s CRUD. V prípade GitHub ide o požiadavky typu POST s iba jedným koncovým bodom https: // api.github.com / graphql
Keďže ide o POST požiadavku, môže so sebou niesť text ako JSON, cez ktorý budú naše operácie GraphQL. Tieto operácie môžu byť typu dopyt ak chce len prečítať nejaké informácie, alebo to môže byť mutácia v prípade, že je potrebné údaje upraviť.
Na uskutočňovanie hovorov cez GraphQL API môžete použiť GQL prehľadávač GraphQL. Zoznámte sa s týmto GraphQL dopyt načítať rovnaký druh údajov (verejné biografické údaje používateľa), ako sme to urobili vyššie pomocou funkcie REST.
Žiadosť: POST https: // api.github.com / graphqldopyt
používateľ (prihlásenie: "ranvo")
bio
Odpoveď:
"data":
"user":
"bio": "Milovníci techniky a vedy.". Som z najrôznejších nepríbuzných vecí
servery na kvantovú fyziku.\ r \ nObčas píšem blogové príspevky o vyššie uvedených záujmoch.„
Ako vidíte, odpoveď sa skladá iba z toho, čo ste požadovali, to je životopis používateľa. Konkrétneho používateľa vyberiete zadaním používateľského mena (v mojom prípade je ranvo) a potom požiadate o hodnotu atribútu daného používateľa, v tomto prípade tento atribút je bio. Server API vyhľadá presné konkrétne informácie a odpovie nimi a ničím iným.
Na druhú stranu, GraphQL vám tiež umožní urobiť jednu požiadavku a extrahovať informácie, ktoré by vám vzali viac požiadaviek v tradičnom REST API. Pripomeňme, že všetky požiadavky GraphQL sa odosielajú iba do jedného koncového bodu API. Vezmite si napríklad príklad použitia, keď potrebujete požiadať server API GitHub o životopis používateľa a jeden z jeho kľúčov SSH. Vyžadovalo by si to dve GET žiadosti.
REST požiadavky: ZÍSKAJTE https: // api.github.com /ZÍSKAJTE https: // api.github.com /
Žiadosť GraphQL: POST https: // api.github.com / graphql /
dopyt
používateľ (prihlásenie: "ranvo")
bio
publicKeys (posledný: 1)
hrany
uzol
kľúč
Odpoveď GraphQL:
"data":
"user":
"bio": "Milovníci techniky a vedy.". Som z najrôznejších nepríbuzných vecí
servery na kvantovú fyziku.\ r \ nObčas píšem blogové príspevky o vyššie uvedených záujmoch.„,
"publicKeys":
"hrany": [
"uzol":
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Existujú vnorené objekty, ale ak sa pozriete na svoju požiadavku, dosť sa zhodujú s vašou požiadavkou, aby ste vedeli a v určitom zmysle utvárali štruktúru odpovede, ktorú dostanete .
Záver
GraphQL má svoju vlastnú krivku učenia, ktorá je veľmi strmá alebo vôbec nie strmá v závislosti od toho, o koho sa pýtate. Z objektívneho hľadiska vám môžem uviesť nasledujúce skutočnosti. Je flexibilný, ako ste videli vyššie, je introspektívny - to znamená, že môžete dotazovať API GraphQL na samotné API. Aj keď nebudete pripravovať svoj server API pomocou tohto servera, je pravdepodobné, že budete musieť pracovať s rozhraním API, ktoré umožňuje iba GraphQL.
Tu sa môžete dozvedieť viac informácií o jeho technických požiadavkách. Ak chcete volať GraphQL API z miestnej pracovnej stanice, použite Graphiql.
