Phenquestions
TL; DR versioon
Ühes eelmises postituses arutasime lühidalt, milline on GitHubi API v3 kasutamine. See versioon on loodud liidestamiseks nagu iga teine REST API. Iga ressursi jaoks, millele peate juurde pääsema ja / või mida muutma, on lõpp-punktid. Iga kasutaja, organisatsiooni, hoidla ja muu kohta on olemas lõpp-punktid. Näiteks on igal kasutajal oma API lõpp-punkt aadressil https: // api.github.com / users /
GitHub API v4 kasutab seevastu GraphQL-i, kus QL tähendab Query Language. GraphQL on uus viis teie API-de kujundamiseks. Nii nagu palju REST-i API-dena pakutavaid veebiteenuseid, mitte ainult GitHubi pakutavaid, on ka palju veebiteenuseid, mis võimaldavad teil nendega GraphQL-i kaudu liidestuda.
Suurim erinevus, mida märkate GraphQL-i ja REST-i API vahel, on see, et GraphQL suudab töötada ühe API-lõpp-punktina. GitHubi API v4 puhul on see lõpp-punkt https: // api.github.com / graphql ja see ongi. Te ei pea muretsema juur-URI lõpus pikkade stringide lisamise ega lisateabe saamiseks päringustringi parameetri pakkumise pärast. Saate sellele API-le lihtsalt JSON-i sarnase argumendi, küsides ainult vajalikke asju, ja saate JSON-i kasuliku koormuse tagasi täpselt sama teabega, mida taotlesite. Te ei pea tegelema soovimatu teabe filtreerimisega ega kannatama jõudluse tõttu suurte vastuste tõttu.
Mis on REST API?
Noh, REST tähistab esindusriikide ülekandmist ja API tähendab rakenduste programmeerimise liidest. REST-i API-st või RESTful-i API-st on saanud enamiku kaasaegsete klient-server rakenduste taga peamine disainifilosoofia. Idee tuleneb vajadusest eraldada rakenduse erinevad komponendid, näiteks kliendipoolne kasutajaliides ja serveripoolne loogika.
Nii et kliendi ja serveri vaheline seanss on tavaliselt kodakondsuseta. Kui veebileht ja sellega seotud skriptid on laaditud, saate nendega edasi suhelda ja kui toimingu sooritate (nt vajutage saatmisnuppu), saadetakse saatmistaotlus koos kogu kontekstuaalse teabega, mida veebiserver selle taotluse töötlemiseks vajab ( nagu kasutajanimi, märgid jne). Rakendus läheb üle ühest olekust teise, kuid ilma kliendi ja serveri vahelise pideva ühenduse vajaduseta.
REST määratleb kliendi ja serveri vaheliste piirangute kogumi ning side saab toimuda ainult nende piirangute all. Näiteks REST over HTTP kasutab tavaliselt CRUD-mudelit, mis tähistab loomist, lugemist, värskendamist ja kustutamist ning HTTP-meetodid nagu POST, GET, PUT ja DELETE aitavad teil neid toiminguid ja neid toiminguid teha üksi. Vanad sissetungimistehnikad, nagu SQL-i süstid, ei ole võimalik koos rangelt kirjutatud REST API-ga (kuigi see on REST ei ole turvarohi).
See aitab üsna palju ka kasutajaliidese arendajaid! Kuna kõik, mis teile HTTP-päringust saadakse, on tüüpiline tekstivoog (mõnikord vormindatud JSON-iks), saate hõlpsasti veebibrauseri või rakenduse (teie eelistatud keeles) juurutada, muretsemata serveripoole arhitektuuri pärast. Lugesite selliste teenuste nagu Reddit, Twitter või Facebook API dokumentatsiooni ja saate neile või kolmandate osapoolte klientidele laiendeid kirjutada teie valitud keeles, kuna olete tagatud, et API käitumine on endiselt sama.
Ja vastupidi, serveril pole vahet, kas kasutajaliides on kirjutatud Go, Ruby või Python. Kas see on brauser, rakendus või CLI. Ta lihtsalt "näeb" taotlust ja vastab asjakohaselt.
Mis on GraphQL?
Nagu mis tahes arvutimaailmas, said REST-i API-d suuremaks ja keerukamaks ning samal ajal tahtsid inimesed neid kiiremini ja lihtsamalt rakendada ja tarbida. Seetõttu tuli Facebook välja GraphQLi ideega ja avas selle hiljem. QL GraphQLis tähendab lühendit Query Language.
GraphQL võimaldab klientidel teha eelnevalt määratletud parameetrite ja vastustega jäikade API-kõnede tegemise asemel väga konkreetseid API-päringuid. See on palju lihtsam, kuna server vastab seejärel täpselt nende andmetega, mida teilt küsisite, ilma et oleks midagi üleliigset.
Vaadake seda REST-i taotlust ja sellele vastavat vastust. See taotlus on mõeldud ainult kasutaja avaliku eluloo vaatamiseks.
Taotlus: Hangi https: // api.github.com / users /Vastus:
"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 / follow / other_user ",
"gists_url": "https: // api.github.com / users / octocat / gists / gist_id ",
"starred_url": "https: // api.github.com / users / octocat / tärniga tähistatud / owner / repo ",
"subscriptions_url": "https: // api.github.com / users / octocat / subscriptions ",
"organisatsiooni_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 ",
"saadud_sündmused_url": "https: // api.github.com / users / octocat / vastuvõetud_sündmused ",
"type": "Kasutaja",
"site_admin": vale,
"nimi": "Octocat",
"ettevõte": "GitHub",
"blog": "http: // www.github.com / blog ",
"asukoht": "San Francisco",
"email": null,
"palgatav": null,
"bio": null,
"public_repos": 8,
"public_gists": 8,
"jälgijad": 2455,
"järgmine": 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Olen kasutanud kasutajanime octocat, kuid võite selle asendada valitud kasutajanimega ja kasutada seda URL-i cURL käsureal või Postmanis, kui vajate GUI-d. Kuigi taotlus oli lihtne, mõelge kogu lisateabele, mida selle vastuse kaudu saate. Kui töötleksite miljoni sellise kasutaja andmeid ja filtreeriksite kõik tarbetud andmed välja, siis pole see tõhus. Te raiskate ribalaiust, mälu ja arvutust, et hankida, salvestada ja filtreerida kõik miljonid võtme-väärtuse lisapaarid, mida te kunagi ei kavatse
Ka vastuse ülesehitus pole midagi, mida te eelnevalt teate. See JSON-vastus on samaväärne Pythoni sõnastikuobjektiga või JavaScripti objektiga. Teised lõpp-punktid vastavad JSON-i objektidele, mis võivad koosneda pesastatud objektidest, objekti sisestatud pesade loendist või mis tahes meelevaldsest JSON-i andmetüüpide kombinatsioonist. Spetsiifika saamiseks peate viitama dokumentatsioonile. Taotluse töötlemisel peate olema kursis selle vorminguga, mis muutub lõpp-punktist teise.
GraphQL ei tugine serveris CRUD-toimingute tegemisel HTTP-verbidele nagu POST, GET, PUT ja DELETE. Selle asemel on kõigi CRUD-ga seotud toimingute jaoks ainult ühte tüüpi HTTP-päringu tüüp ja endopint. GitHubi puhul hõlmab see POST-tüüpi päringuid, millel on ainult üks lõpp-punkt https: // api.github.com / graphql
POST-päringuna võib see endaga kaasas olla JSON-laadse tekstikorpuse, mille kaudu toimivad meie GraphQL-i toimingud. Need toimingud võivad olla tüüpilised päring kui kõik, mida ta teha tahab, on mõne teabe lugemine või see võib olla mutatsioon juhul kui andmeid on vaja muuta.
GraphQL API kõnede tegemiseks võite kasutada GitHubi GraphQL explorerit. Heitke pilk sellele GraphQL-ile päring sama tüüpi andmete (kasutaja avalik elulugu) toomiseks, nagu me tegime ülal REST-i abil.
Taotlus: POST https: // api.github.com / graphqlpäring
kasutaja (sisselogimine: "ranvo")
bio
Vastus:
"andmed":
"kasutaja":
"bio": "Tehnika- ja teadushuvilised. Ma tegelen igasuguste mitteseotud asjadega
serverid kvantfüüsikale.\ r \ nVahel kirjutan blogipostitusi ülalnimetatud huvide kohta."
Nagu näete, koosneb vastus ainult sellest, mida te palusite, see on kasutaja elulugu. Te valite konkreetse kasutaja, edastades kasutajanime (minu puhul on see nii ranvo) ja siis küsite selle kasutaja atribuudi väärtust, antud juhul see atribuut on bio. API server otsib täpse konkreetse teabe ja vastab sellega, mitte millegi muuga.
Tagaküljel laseme GraphQLil teha ka ühe päringu ja eraldada teave, mis oleks tavapärases REST API-s toonud teile mitu taotlust. Tuletame meelde, et kõik GraphQL-i päringud tehakse ainult ühele API-lõpp-punktile. Võtame näiteks kasutusjuhtumi, kus peate küsima GitHubi API-serverilt kasutaja eluloo ja selle ühe SSH-võtme. See nõuaks kahte GET-i taotlust.
REST taotlused: Hangi https: // api.github.com /Hangi https: // api.github.com /
GraphQL-i taotlus: POST https: // api.github.com / graphql /
päring
kasutaja (sisselogimine: "ranvo")
bio
publicKeys (viimane: 1)
servad
sõlm
võti
GraphQLi vastus:
"andmed":
"kasutaja":
"bio": "Tehnika- ja teadushuvilised. Ma tegelen igasuguste mitteseotud asjadega
serverid kvantfüüsikale.\ r \ nVahel kirjutan blogipostitusi ülalnimetatud huvide kohta.",
"publicKeys":
"servad": [
"sõlm":
"võti": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
On pesastatud objekte, kuid kui te vaatate teie taotlust, siis need vastavad teie taotlusele üsna palju, et saaksite teada saada ja mõnes mõttes kujundada saadud vastuse struktuuri .
Järeldus
GraphQL-l on oma õppekõver, mis on väga järsk või üldse mitte järsk, sõltuvalt sellest, kellelt küsite. Objektiivsest vaatenurgast võin teile esitada järgmised faktid. See on paindlik, nagu te eespool nägite, see on introspektiivne - see tähendab, et saate GraphQL API-lt pärida API enda kohta. Isegi kui te ei kavatse oma API-serverit selle abil üles ehitada, peate tõenäoliselt liidestuma API-ga, mis lubab ainult GraphQL-i.
Siit saate natuke rohkem teada selle tehniliste võimaluste kohta ja kui soovite oma kohalikult tööjaamalt GraphQL API kõnesid teha, siis kasutage Graphiqli.
