Phenquestions
TL; DR različica
V enem od prejšnjih prispevkov smo na kratko razpravljali o tem, kako je uporabljati GitHub API v3. Ta različica je zasnovana tako, da jo lahko povezujemo z drugimi API-ji REST. Za vsak vir obstajajo končne točke, do katerih morate dostopati in / ali jih spremeniti. Obstajajo končne točke za vsakega uporabnika, vsako organizacijo, vsako skladišče itd. Vsak uporabnik ima na primer svojo končno točko API na https: // api.github.com / uporabniki /
GitHub API v4 pa uporablja GraphQL, kjer QL pomeni Query Language. GraphQL je nov način oblikovanja vaših API-jev. Tako kot obstaja veliko spletnih storitev, ki so na voljo kot REST API-ji, ne le tiste, ki jih ponuja GitHub, obstaja tudi veliko spletnih storitev, ki vam omogočajo vmesnik z njimi prek GraphQL.
Najpomembnejša razlika, ki jo boste opazili med API-jem GraphQL in REST, je ta, da lahko GraphQL deluje z eno končno točko API-ja. V primeru GitHub API v4 je ta končna točka https: // api.github.com / graphql in to je to. Ni vam treba skrbeti, ali boste na koncu korenskega URI-ja dodali dolge nize ali za dodatne informacije navedli parameter poizvedbenega niza. Temu API-ju preprosto pošljete argument, podoben JSON, in povprašate samo po stvareh, ki jih potrebujete, in dobite nazaj tovor JSON s popolnoma enakimi informacijami, kot ste jih zahtevali. Ni vam treba ukvarjati s filtriranjem neželenih informacij ali pa zaradi velikih odzivov trpite zaradi režijskih stroškov.
Kaj je REST API?
No, REST je kratica za Represent State Transfer, API pa za Application Programming Interface. API REST ali API »RESTful« je postal jedro filozofije oblikovanja večine sodobnih aplikacij odjemalec-strežnik. Ideja izhaja iz potrebe po ločitvi različnih komponent aplikacije, kot sta uporabniški vmesnik na strani odjemalca in logika na strani strežnika.
Tako je seja med odjemalcem in strežnikom običajno brez državljanstva. Ko se spletna stran in z njo povezani skripti naložijo, lahko še naprej komunicirate z njimi in ko izvedete dejanje (na primer pritisnite gumb za pošiljanje), se pošlje zahteva za pošiljanje skupaj z vsemi kontekstualnimi informacijami, ki jih spletni strežnik potrebuje za obdelavo te zahteve ( kot so uporabniško ime, žetoni itd.). Aplikacija prehaja iz enega stanja v drugo, vendar brez stalne potrebe po povezavi med odjemalcem in strežnikom.
REST definira nabor omejitev med odjemalcem in strežnikom, komunikacija pa se lahko zgodi le pod temi omejitvami. Na primer REST over HTTP običajno uporablja model CRUD, ki pomeni Ustvarjanje, branje, posodabljanje in brisanje, metode HTTP, kot so POST, GET, PUT in DELETE, pa vam pomagajo izvajati te operacije in te operacije same. Stare tehnike vdorov, kot so vbrizgavanja SQL, niso možne z nečim, kot je tesno napisan REST API (čeprav REST ni varnostna rešitev).
Prav tako zelo pomaga razvijalcem uporabniškega vmesnika! Ker prejmete zahtevo HTTP, je tipičen tok besedila (včasih oblikovan kot JSON), lahko enostavno namestite spletno stran za brskalnike ali aplikacijo (v vašem želenem jeziku), ne da bi vas skrbelo za strežniško arhitekturo. Preberete dokumentacijo API-ja za storitve, kot so Reddit, Twitter ali Facebook, in lahko za njih ali neodvisne odjemalce napišete razširitve v izbranem jeziku, saj vam zagotavlja, da bo vedenje API-ja še vedno enako.
Nasprotno pa strežniku ni vseeno, ali je čelna stran napisana v Go, Ruby ali Python. Ne glede na to, ali gre za brskalnik, aplikacijo ali CLI. Samo "vidi" zahtevo in se ustrezno odzove.
Kaj je GraphQL?
Kot pri vsem na svetu računalnikov so tudi API-ji REST postali večji in bolj zapleteni, hkrati pa so jih ljudje želeli hitreje in preprosteje implementirati in porabiti. Zato je Facebook prišel na idejo GraphQL in jo kasneje odprto kodiral. QL v GraphQL pomeni Query Language.
GraphQL omogoča odjemalcem, da oddajo zelo specifične zahteve za API, namesto da izvajajo toge klice API z vnaprej določenimi parametri in odzivi. Preprosteje je, ker se strežnik nato odzove s točno takimi podatki, za katere ste ga zahtevali, brez odvečnih podatkov.
Oglejte si to zahtevo REST in njen ustrezen odgovor. Ta zahteva je namenjena ogledu samo uporabnikove javne biografije.
Zahteva: GET https: // api.github.com / uporabniki /Odgovor:
"login": "oktobar",
"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 ",
"subscription_url": "https: // api.github.com / users / octocat / subscription ",
"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 ",
"received_events_url": "https: // api.github.com / users / octocat / received_events ",
"type": "Uporabnik",
"site_admin": napačno,
"name": "Oktokat",
"company": "GitHub",
"blog": "http: // www.github.com / blog ",
"location": "San Francisco",
"email": null,
"hireable": null,
"bio": nič,
"public_repos": 8,
"public_gists": 8,
"sledilci": 2455,
"naslednje": 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Uporabil sem uporabniško ime octocat, vendar ga lahko nadomestite z uporabniškim imenom po svoji izbiri in uporabite cURL, če želite zahtevo v ukazni vrstici ali Postman, če potrebujete GUI. Čeprav je bila zahteva preprosta, razmislite o vseh dodatnih informacijah, ki jih dobite s tem odzivom. Če bi obdelovali podatke milijona takih uporabnikov in filtrirali vse nepotrebne podatke, potem to ni učinkovito. Zapravljate pasovno širino, pomnilnik in račune pri pridobivanju, shranjevanju in filtriranju vseh milijonov dodatnih parov ključ-vrednost, ki jih nikoli ne boste
Tudi struktura odziva ni nekaj, kar poznate vnaprej. Ta odgovor JSON je enakovreden slovarskemu objektu v Pythonu ali objektu v JavaScript. Druge končne točke se bodo odzvale z objekti JSON, ki so lahko sestavljeni iz ugnezdenih objektov, ugnezdenega seznama znotraj predmeta ali katere koli poljubne kombinacije podatkovnih tipov JSON, zato boste morali napotiti dokumentacijo, da boste dobili podrobnosti. Ko obdelujete zahtevo, morate biti seznanjeni s to obliko, ki se spreminja od končne točke do končne točke.
GraphQL se pri izvajanju CRUD operacij na strežniku ne zanaša na glagole HTTP, kot so POST, GET, PUT in DELETE. Namesto tega obstaja samo ena vrsta zahteve HTTP in endopint za vse operacije, povezane s CRUD. V primeru GitHub to vključuje zahteve tipa POST z samo eno končno točko https: // api.github.com / graphql
Ker je zahteva POST, lahko s seboj nosi besedilo, podobno JSON-u, skozi katerega bodo naše operacije GraphQL. Te operacije so lahko vrste poizvedba če želi le prebrati nekaj informacij ali pa je to lahko mutacija v primeru, da je treba podatke spremeniti.
Za klice API-jev GraphQL lahko uporabite GitHub-ov raziskovalec GraphQL. Oglejte si ta GraphQL poizvedba za pridobitev iste vrste podatkov (uporabnikova javna biografija), kot smo to storili zgoraj z uporabo REST.
Zahteva: POST https: // api.github.com / graphqlpoizvedba
uporabnik (prijava: "ranvo")
bio
Odgovor:
"podatki":
"uporabnik":
"bio": "Ljubitelji tehnike in znanosti. Sama se ukvarjam z vsemi vrstami nepovezanih stvari
strežniki za kvantno fiziko.\ r \ n Občasno pišem objave v spletnih dnevnikih o zgornjih zanimanjih."
Kot lahko vidite, je odgovor sestavljen le iz tistega, kar ste zahtevali, to je biografija uporabnika. Določenega uporabnika izberete s posredovanjem uporabniškega imena (v mojem primeru je ranvo) in nato zahtevate vrednost atributa tega uporabnika, v tem primeru je ta atribut bio. Strežnik API poišče natančno določene informacije in odgovori s tem in nič drugim.
Na drugi strani vam GraphQL omogoča tudi, da naredite eno samo zahtevo in izvlečete informacije, ki bi vam v tradicionalnem API-ju REST prinesle več zahtev. Spomnimo se, da so vse zahteve GraphQL narejene samo eni končni točki API. Vzemimo na primer primer uporabe, ko morate strežnik API GitHub vprašati za biografijo uporabnika in enega od njegovih SSH ključev. Potrebovali bi dve zahtevi GET.
POČITKI Zahteve: GET https: // api.github.com /PRIDOBITE https: // api.github.com /
Zahteva za GraphQL: POST https: // api.github.com / graphql /
poizvedba
uporabnik (prijava: "ranvo")
bio
publicKeys (zadnji: 1)
robovi
vozlišče
tipko
Odgovor GraphQL:
"podatki":
"uporabnik":
"bio": "Ljubitelji tehnike in znanosti. Sama se ukvarjam z vsemi vrstami nepovezanih stvari
strežniki za kvantno fiziko.\ r \ n Občasno pišem objave v spletnih dnevnikih o zgornjih zanimanjih.",
"publicKeys":
"robovi": [
"vozlišče":
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Obstajajo ugnezdeni objekti, vendar če pogledate svojo zahtevo, se v veliki meri ujemajo z vašo zahtevo, tako da lahko veste in v nekem smislu oblikujete strukturo odgovora, ki ga dobite .
Zaključek
GraphQL ima lastno učno krivuljo, ki je zelo strma ali pa sploh ni strma, odvisno od tega, koga vprašate. Z objektivnega stališča vam lahko predstavim naslednja dejstva. Je prilagodljiv, kot ste videli zgoraj, je introspektiven - se pravi, lahko GraphQL API povprašate o samem API-ju. Tudi če svojega strežnika API ne boste gradili z njim, boste verjetno morali vmesnik z API-jem, ki omogoča samo GraphQL.
Tukaj lahko izveste nekaj več o njegovih tehničnih lastnostih in če želite klicati API API GraphQL s svoje lokalne delovne postaje, uporabite Graphiql.
