Phenquestions
TL; DR versija
Vienā no iepriekšējām ziņām īsi apspriedām, kā ir izmantot GitHub API v3. Šī versija ir paredzēta saskarnei tāpat kā jebkura cita REST API. Katram resursam ir pieejami galapunkti, kuriem jums ir jāpiekļūst un / vai jāmaina. Katram lietotājam, katrai organizācijai, katram krātuvei un tā tālāk ir galapunkti. Piemēram, katram lietotājam ir savs API galapunkts vietnē https: // api.github.com / users /
Savukārt GitHub API v4 izmanto GraphQL, kur QL nozīmē Query Language. GraphQL ir jauns API veidošanas veids. Tāpat kā ir daudz tīmekļa pakalpojumu, kas tiek piedāvāti kā REST API, ne tikai tie, kurus piedāvā GitHub, ir arī daudzi tīmekļa pakalpojumi, kas ļauj jums ar tiem saskarties, izmantojot GraphQL.
Lielākā atšķirība, ko pamanīsit starp GraphQL un REST API, ir tā, ka GraphQL var strādāt ar vienu API galapunktu. GitHub API v4 gadījumā šis gala punkts ir https: // api.github.com / graphql un tas arī viss. Jums nav jāuztraucas par garu virkņu pievienošanu saknes URI beigās vai papildu informācijas piegādei vaicājuma virknes parametru. Jūs vienkārši nosūtiet šai API ar JSON līdzīgu argumentu, lūdzot tikai jums nepieciešamās lietas, un jūs saņemsit atpakaļ JSON lietderīgo kravu ar tieši to pašu informāciju, kuru pieprasījāt. Jums nav jārisina nevēlamas informācijas filtrēšana vai jācieš no veiktspējas piesātinātības lielo atbilžu dēļ.
Kas ir REST API?
Nu, REST nozīmē pārstāvniecības stāvokļa pārsūtīšanu un API nozīmē lietojumprogrammu saskarni. REST API jeb “RESTful” API ir kļuvusi par galveno dizaina filozofiju modernāko klientu-serveru lietojumprogrammu pamatā. Ideja rodas no nepieciešamības nošķirt dažādus lietojumprogrammas komponentus, piemēram, klienta lietotāja saskarni un servera puses loģiku.
Tātad sesija starp klientu un serveri parasti ir bezvalstnieks. Kad vietne un ar to saistītie skripti ir ielādēti, varat turpināt tos mijiedarboties, un, veicot darbību (piemēram, nospiežot pogu Sūtīt), tiek nosūtīts sūtīšanas pieprasījums kopā ar visu kontekstuālo informāciju, kas tīmekļa serverim ir nepieciešama, lai apstrādātu šo pieprasījumu ( piemēram, lietotājvārds, žetoni utt.). Lietojumprogramma pāriet no viena stāvokļa uz citu, bet bez pastāvīgas nepieciešamības izveidot savienojumu starp klientu un serveri.
REST definē ierobežojumu kopumu starp klientu un serveri, un saziņa var notikt tikai saskaņā ar šiem ierobežojumiem. Piemēram, REST over HTTP parasti izmanto CRUD modeli, kas nozīmē Izveidot, Lasīt, Atjaunināt un Dzēst, un tādas HTTP metodes kā POST, GET, PUT un DELETE palīdz jums veikt šīs operācijas un tikai šīs darbības. Vecās ielaušanās metodes, piemēram, SQL injekcijas, nav iespējamas ar kaut ko līdzīgu cieši uzrakstītai REST API (lai gan tas ir REST nav drošības panaceja).
Tas diezgan daudz palīdz arī UI izstrādātājiem! Tā kā viss, ko saņemat no HTTP pieprasījuma, ir tipiska teksta straume (dažreiz formatēta kā JSON), varat viegli ieviest tīmekļa lapu pārlūkprogrammām vai lietotni (vēlamajā valodā), neuztraucoties par servera puses arhitektūru. Jūs lasāt API dokumentāciju tādiem pakalpojumiem kā Reddit, Twitter vai Facebook un varat rakstīt paplašinājumus tiem vai trešo pušu klientiem izvēlētajā valodā, jo jums tiek garantēts, ka API darbība joprojām būs tāda pati.
Un otrādi, serverim ir vienalga, vai priekšgals ir rakstīts Go, Ruby vai Python. Vai tas ir pārlūks, lietotne vai CLI. Tā vienkārši “redz” pieprasījumu un atbilstoši reaģē.
Kas ir GraphQL?
Tāpat kā jebkuram citam datoru pasaulē, arī REST API kļuva lielāki un sarežģītāki, un tajā pašā laikā cilvēki vēlējās tos ieviest un patērēt ātrāk un vienkāršāk. Tāpēc Facebook nāca klajā ar ideju par GraphQL un vēlāk to atklāja. QL GraphQL nozīmē Query Language.
GraphQL ļauj klientiem veikt ļoti specifiskus API pieprasījumus, nevis veikt stingrus API izsaukumus ar iepriekš definētiem parametriem un atbildēm. Tas ir daudz vienkāršāk, jo serveris pēc tam atbild ar precīzi datiem, kurus jūs tam prasījāt, bez liekiem.
Apskatiet šo REST pieprasījumu un tā atbilstošo atbildi. Šis pieprasījums ir paredzēts, lai skatītu tikai lietotāja publisko biogrāfiju.
Pieprasījums: IEGŪT https: // api.github.com / users /Atbilde:
"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 / starred / owner / repo ",
"subscriptions_url": "https: // api.github.com / users / octocat / subscriptions ",
"organisations_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 ",
"receives_events_url": "https: // api.github.com / users / octocat / seen_events ",
"type": "Lietotājs",
"site_admin": nepatiesa,
"name": "The Octocat",
"uzņēmums": "GitHub",
"emuārs": "http: // www.github.com / blog ",
"atrašanās vieta": "Sanfrancisko",
"e-pasts": null,
"iznomājams": null,
"bio": nulle,
"public_repos": 8,
"public_gists": 8,
"sekotāji": 2455,
"šādi": 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Esmu izmantojis lietotājvārdu octocat, taču jūs varat to aizstāt ar izvēlēto lietotājvārdu un izmantot cURL, lai veiktu šo pieprasījumu komandrindā vai Pastnieks, ja jums nepieciešama GUI. Lai gan pieprasījums bija vienkāršs, padomājiet par visu papildu informāciju, ko saņemat no šīs atbildes. Ja jums būtu jāapstrādā dati no miljona šādu lietotāju un jāfiltrē visi nevajadzīgie dati, tad tas nav efektīvi. Jūs iztērējat joslas platumu, atmiņu un aprēķinus, lai iegūtu, uzglabātu un filtrētu visus miljonus papildu atslēgas un vērtības pārus, kurus jūs nekad nedarīsit
Arī atbildes struktūra nav tas, ko jūs zināt iepriekš. Šī JSON atbilde ir līdzvērtīga vārdnīcas objektam Python vai objektam JavaScript. Citi galapunkti reaģēs ar JSON objektiem, kas var sastāvēt no ligzdotiem objektiem, objekta ligzdotajiem sarakstiem vai jebkuras patvaļīgas JSON datu tipu kombinācijas, un, lai iegūtu specifiku, jums būs jānorāda dokumentācija. Apstrādājot pieprasījumu, jums jāzina šis formāts, kas mainās no gala uz galapunktu.
Lai veiktu CRUD operācijas serverī, GraphQL paļaujas uz tādiem HTTP darbības vārdiem kā POST, GET, PUT un DELETE. Tā vietā visām CRUD saistītajām darbībām ir tikai viena veida HTTP pieprasījuma tips un endopints. GitHub gadījumā tas ietver POST tipa pieprasījumus tikai ar vienu gala punktu https: // api.github.com / graphql
Būdams POST pieprasījums, tam var būt līdzīgs JSON teksts, caur kuru tiks izmantotas mūsu GraphQL darbības. Šīs darbības var būt tipiskas vaicājumu ja viss, ko tā vēlas darīt, ir izlasīt kādu informāciju vai arī tā var būt mutācija ja dati ir jāmaina.
Lai veiktu GraphQL API izsaukumus, varat izmantot GitHub GraphQL Explorer. Apskatiet šo GraphQL vaicājumu lai iegūtu tāda paša veida datus (lietotāja publisko biogrāfiju) kā iepriekš, izmantojot REST.
Pieprasījums: POST https: // api.github.com / graphqlvaicājums
lietotājs (login: "ranvo")
bio
Atbilde:
"dati":
"lietotājs":
"bio": "Tehnikas un zinātnes entuziasti. Es nodarbojos ar visdažādākajām nesaistītām lietām
serveri kvantu fizikai.\ r \ nEs pa laikam rakstu emuāra ziņas par iepriekš minētajām interesēm."
Kā redzat, atbilde sastāv tikai no tā, ko jūs lūdzāt, tas ir lietotāja biogrāfija. Jūs izvēlaties konkrētu lietotāju, nododot lietotājvārdu (manā gadījumā tas ir ranvo) un pēc tam jūs pieprasāt šī lietotāja atribūta vērtību, šajā gadījumā šis atribūts ir bio. API serveris meklē precīzu konkrētu informāciju un atbild ar to, un neko citu.
No otras puses, GraphQL arī pieņemsim, ka jūs veicat vienu pieprasījumu un iegūstat informāciju, kas jums būtu prasījusi vairākus pieprasījumus tradicionālajā REST API. Atgādināsim, ka visi GraphQL pieprasījumi tiek veikti tikai vienam API galapunktam. Piemēram, izmantojiet gadījumu, kad jums jāpieprasa GitHub API serverim lietotāja biogrāfija un viena no tā SSH atslēgām. Tam būtu nepieciešami divi GET pieprasījumi.
ATPŪTA pieprasījumi: IEGŪT https: // api.github.com /IEGŪT https: // api.github.com /
GraphQL pieprasījums: POST https: // api.github.com / graphql /
vaicājums
lietotājs (login: "ranvo")
bio
publicKeys (pēdējais: 1)
malas
mezgls
taustiņu
GraphQL atbilde:
"dati":
"lietotājs":
"bio": "Tehnikas un zinātnes entuziasti. Es nodarbojos ar visdažādākajām nesaistītām lietām no
serveri kvantu fizikai.\ r \ nEs pa laikam rakstu emuāra ziņas par iepriekš minētajām interesēm.",
"publicKeys":
"malas": [
"mezgls":
"atslēga": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Ir ligzdoti objekti, bet, ja paskatās uz jūsu pieprasījumu, tie gandrīz atbilst jūsu pieprasījumam, lai jūs varētu zināt un savā ziņā veidot saņemtās atbildes struktūru .
Secinājums
GraphQL nāk ar savu mācīšanās līkni, kas ir ļoti stāva vai nemaz nav atkarīga no tā, kurš ir tas, ko jūs jautājat. No objektīvā viedokļa es varu jums izklāstīt šādus faktus. Tas ir elastīgs, kā jūs redzējāt iepriekš, tas ir introspektīvs - tas ir, jūs varat vaicāt GraphQL API par pašu API. Pat ja jūs nevēlaties veidot savu API serveri, izmantojot to, iespējams, jums būs jāsaskaras ar API, kas ļauj tikai GraphQL.
Šeit varat uzzināt mazliet vairāk par tā tehniskajām iespējām un, ja vēlaties veikt vietējās darbstacijas GraphQL API zvanus, izmantojiet Graphiql.
