Phenquestions
TL; DR versija
Viename iš ankstesnių įrašų trumpai aptarėme, koks yra „GitHub“ API v3 naudojimas. Ši versija skirta sąsajai, kaip ir bet kuri kita REST API. Kiekvienam šaltiniui, kurį turite pasiekti ir (arba) modifikuoti, yra galinių taškų. Kiekvienam vartotojui, kiekvienai organizacijai, kiekvienai saugyklai ir pan. Yra galiniai taškai. Pavyzdžiui, kiekvienas vartotojas turi savo API galutinį tašką adresu https: // api.github.com / users /
Kita vertus, „GitHub“ API v4 naudoja „GraphQL“, kur QL reiškia „Query Language“. „GraphQL“ yra naujas būdas kurti jūsų API. Kaip ir daugybė žiniatinklio paslaugų, siūlomų kaip REST API, ne tik tos, kurias siūlo „GitHub“, yra daugybė interneto paslaugų, kurios leidžia sąveikauti su jomis per „GraphQL“.
Didžiausias skirtumas, kurį pastebėsite tarp „GraphQL“ ir „REST API“, yra tai, kad „GraphQL“ gali dirbti su vienu API galiniu tašku. „GitHub“ API v4 atveju šis galutinis taškas yra https: // api.github.com / graphql ir viskas. Jums nereikia jaudintis dėl ilgų eilučių pridėjimo šakninio URI pabaigoje arba pateikti užklausos eilutės parametrą, kad gautumėte papildomos informacijos. Jūs tiesiog siunčiate į JSON panašų argumentą į šią API, prašydami tik jums reikalingų dalykų, ir jūs gausite JSON naudingąją apkrovą su ta pačia informacija, kurios prašėte. Jums nereikia užsiimti nereikalingos informacijos filtravimu ar dėl didelių atsakymų kenčia nuo našumo.
Kas yra REST API?
Na, REST reiškia „Reprezentacinės valstybės perkėlimas“, o „API“ - „Programming Interface“. REST API arba „RESTful“ API tapo pagrindine dizaino filosofija, kuriančia daugumą šiuolaikinių kliento-serverio programų. Idėja kyla iš poreikio atskirti įvairius programos komponentus, tokius kaip kliento vartotojo sąsaja ir serverio logika.
Taigi seansas tarp kliento ir serverio paprastai yra be pilietybės. Įkėlę tinklalapį ir susijusius scenarijus, galite toliau bendrauti su jais ir atlikę veiksmą (pvz., Paspausdami siuntimo mygtuką), tada siunčiama užklausa kartu su visa kontekstine informacija, kurios žiniatinklio serveriui reikia apdoroti šią užklausą ( pvz., vartotojo vardas, žetonai ir kt.). Programa pereina iš vienos būsenos į kitą, tačiau nereikia nuolatinio ryšio tarp kliento ir serverio.
REST apibrėžia apribojimų rinkinį tarp kliento ir serverio, o ryšys gali vykti tik esant šiems apribojimams. Pavyzdžiui, „REST over HTTP“ paprastai naudoja CRUD modelį, kuris reiškia „Sukurti, Skaityti, Atnaujinti ir Ištrinti“, o HTTP metodai, tokie kaip POST, GET, PUT ir DELETE, padeda atlikti tas operacijas ir tas operacijas. Senos įsilaužimo technikos, tokios kaip SQL injekcijos, nėra galimybės naudojant panašiai kaip griežtai parašytą REST API (nors REST nėra saugumo panacėja).
Tai taip pat nemažai padeda vartotojo sąsajos kūrėjams! Kadangi viskas, ko gaunate iš HTTP užklausos, yra įprastas teksto srautas (kartais suformatuotas kaip JSON), galite lengvai įdiegti tinklalapį naršyklėms arba programą (jūsų pageidaujama kalba), nesijaudindami dėl serverio pusės architektūros. Perskaitėte tokių paslaugų kaip „Reddit“, „Twitter“ ar „Facebook“ API dokumentaciją ir galite parašyti plėtinius jiems ar trečiųjų šalių klientams pasirinkta kalba, nes esate garantuoti, kad API veiks vis tiek.
Ir atvirkščiai, serveriui nesvarbu, ar sąsaja yra parašyta „Go“, „Ruby“ ar „Python“. Nesvarbu, ar tai naršyklė, ar programa, ar CLI. Ji tiesiog „mato“ prašymą ir tinkamai atsako.
Kas yra GraphQL?
Kaip ir bet kur kompiuterių pasaulyje, REST API tapo didesnė ir sudėtingesnė, todėl žmonės norėjo jas įdiegti ir vartoti greičiau ir paprasčiau. Štai kodėl „Facebook“ sugalvojo „GraphQL“ idėją ir vėliau ją atidarė. QL GraphQL reiškia užklausos kalbą.
„GraphQL“ leidžia klientams pateikti labai konkrečias API užklausas, užuot atliekant griežtus API skambučius su iš anksto nustatytais parametrais ir atsakymais. Tai yra daug paprasčiau, nes tada serveris atsako tiksliai su jūsų prašytais duomenimis, be jokių perteklių.
Pažvelkite į šią REST užklausą ir atitinkamą atsakymą. Ši užklausa skirta peržiūrėti tik viešą vartotojo biografiją.
Užklausa: GAUTI https: // api.github.com / users /Atsakymas:
"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 ",
"follow_url": "https: // api.github.com / users / octocat / follow / other_user ",
"gists_url": "https: // api.github.com / users / octocat / gists / gist_id ",
"starred_url": "https: // api.github.com / users / octocat / žvaigždute pažymėtas / owner / repo ",
"subscriptions_url": "https: // api.github.com / users / octocat / subscriptions ",
"organizacijos_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 ",
"ived_events_url ":" https: // api.github.com / vartotojai / „octocat“ / gautas_renginiai ",
"type": "Vartotojas",
"site_admin": klaidinga,
"name": "Aštuonkojis",
„įmonė“: „GitHub“,
„dienoraštis“: „http: // www.github.com / blog “,
„vieta“: „San Franciskas“,
„email“: niekinis,
„nuomojamas“: niekinis,
"bio": niekinis,
„public_repos“: 8,
„public_gists“: 8,
„pasekėjai“: 2455 m,
„sekantis“: 9,
"sukurtas_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Aš naudojau „octocat“ vartotojo vardą, tačiau galite jį pakeisti pasirinktu vartotojo vardu ir naudoti „cURL“, jei norite pateikti šią užklausą komandinėje eilutėje arba „Postman“, jei jums reikia GUI. Nors prašymas buvo paprastas, pagalvokite apie visą papildomą informaciją, kurią gaunate iš šio atsakymo. Jei apdorotumėte milijono tokių vartotojų duomenis ir filtruotumėte visus nereikalingus duomenis naudodamiesi tuo, tai nėra efektyvu. Jūs eikvojate pralaidumą, atmintį ir skaičiavimus, kad gautumėte, kauptumėte ir filtruotumėte visas milijonus papildomų raktų vertės porų, kurių niekada nepadarysite jūs
Taip pat iš anksto nežinote atsakymo struktūros. Šis JSON atsakymas yra lygiavertis „Python“ žodyno objektui arba „JavaScript“ objektui. Kiti galiniai taškai atsakys JSON objektais, kuriuos gali sudaryti įdėti objektai, įdėtas objektų sąrašas arba bet koks savavališkas JSON duomenų tipų derinys. Norėdami sužinoti specifiką, turėsite kreiptis į dokumentaciją. Kai apdorojate užklausą, turite žinoti apie šį formatą, kuris keičiasi nuo galinio taško į galinį.
„GraphQL“, remdamasis CRUD operacijomis serveryje, nesiremia HTTP veiksmažodžiais, tokiais kaip POST, GET, PUT ir DELETE. Vietoj to, visoms su CRUD susijusioms operacijoms yra tik vieno tipo HTTP užklausos tipas ir endopintas. „GitHub“ atveju tai apima POST tipo užklausas, kuriose yra tik vienas galinis taškas https: // api.github.com / graphql
Būdamas POST užklausa, jis gali turėti su JSON panašų teksto turinį, per kurį bus atliekamos mūsų GraphQL operacijos. Šios operacijos gali būti tipinės užklausa jei viskas, ką ji nori padaryti, yra perskaityti tam tikrą informaciją arba tai gali būti mutacija jei reikia pakeisti duomenis.
Norėdami atlikti „GraphQL“ API skambučius, galite naudoti „GitHub“ „GraphQL Explorer“. Pažvelkite į šį GraphQL užklausa gauti tos pačios rūšies duomenis (vartotojo viešą biografiją), kaip tai darėme aukščiau naudodami REST.
Užklausa: POST https: // api.github.com / graphqlužklausa
vartotojas (prisijungti: "ranvo")
bio
Atsakymas:
„duomenys“:
"Vartotojas":
„bio“: „Technikos ir mokslo entuziastai. Aš užsiimu visokiais nesusijusiais dalykais iš
serveriai kvantinei fizikai.\ r \ n Kartais rašau tinklaraščio įrašus apie minėtus pomėgius."
Kaip matote, atsakymą sudaro tik tai, ko paprašėte, tai yra vartotojo pranašumai. Jūs pasirenkate konkretų vartotoją perduodami vartotojo vardą (mano atveju tai yra ranvo) ir tada paprašysite to vartotojo atributo vertės, šiuo atveju tas atributas yra bio. API serveris ieško tikslios konkrečios informacijos ir atsako tuo ir nieko daugiau.
Iš kitos pusės, „GraphQL“ taip pat leiskite pateikti vieną užklausą ir išskleisti informaciją, kuri jums būtų reikalavusi kelių užklausų tradicinėje REST API. Primename, kad visos „GraphQL“ užklausos pateikiamos tik vienam API galiniam taškui. Paimkime, pavyzdžiui, naudojimo atvejį, kai reikia paprašyti „GitHub“ API serverio vartotojo biografijos ir vieno iš jo SSH raktų. Tam reikėtų dviejų GET prašymų.
REST užklausos: GAUTI https: // api.github.com /GAUTI https: // api.github.com /
„GraphQL“ užklausa: POST https: // api.github.com / graphql /
užklausa
vartotojas (prisijungti: "ranvo")
bio
publicKeys (paskutinis: 1)
kraštai
mazgas
Raktas
„GraphQL“ atsakymas:
„duomenys“:
"Vartotojas":
„bio“: „Technikos ir mokslo entuziastai. Aš užsiimu visokiais nesusijusiais dalykais iš
serveriai kvantinei fizikai.\ r \ n Kartais rašau tinklaraščio įrašus apie minėtus pomėgius.",
„publicKeys“:
„kraštai“: [
„mazgas“:
"raktas": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Yra įdėtų objektų, bet jei žiūrite į jūsų užklausą, jie beveik atitinka jūsų užklausą, kad galėtumėte žinoti ir tam tikra prasme formuoti gauto atsakymo struktūrą .
Išvada
„GraphQL“ turi savo mokymosi kreivę, kuri yra labai kieta arba visai ne kieta, atsižvelgiant į tai, ko klausiate. Žiūrint iš objektyvios pusės, aš galiu išdėstyti jums šiuos faktus. Jis yra lankstus, kaip matėte aukščiau, jis yra introspektyvus - tai yra, galite pateikti užklausą „GraphQL API“ apie patį API. Net jei nesiruošiate kurti savo API serverio naudodami jį, greičiausiai turėsite sąsają su API, leidžiančia tik „GraphQL“.
Čia galite sužinoti šiek tiek daugiau apie jo technines savybes ir, jei norite iš savo vietinės darbo vietos skambinti iš „GraphQL“ API, naudokite „Graphiql“.
