Phenquestions
TL; DR verzija
U jednom od prethodnih postova ukratko smo razgovarali o tome kako je koristiti GitHub API v3. Ova je verzija dizajnirana za međusobno povezivanje kao i bilo koji drugi REST API. Postoje krajnje točke za svaki resurs kojem trebate pristupiti i / ili izmijeniti. Postoje krajnje točke za svakog korisnika, svaku organizaciju, svako spremište i tako dalje. Na primjer, svaki korisnik ima svoju API krajnju točku na https: // api.github.com / users /
GitHub API v4, s druge strane, koristi GraphQL gdje QL znači Query Language. GraphQL je novi način dizajniranja vaših API-ja. Baš kao što postoje mnoge web usluge koje se nude kao REST API-ji, ne samo one koje nudi GitHub, tako postoje i mnoge web usluge koje vam omogućuju sučelje s njima putem GraphQL.
Najznačajnija razlika koju ćete primijetiti između GraphQL-a i REST API-ja je ta što GraphQL može raditi na jednoj API završnoj točki. U slučaju GitHub API v4, ova krajnja točka je https: // api.github.com / graphql i to je to. Ne morate se brinuti hoćete li dodati dugačke nizove na kraju korijenskog URI-ja ili pružiti parametar niza upita za dodatne informacije. Jednostavno šaljete argument poput JSON-a ovom API-ju, tražeći samo stvari koje su vam potrebne, a dobit ćete povrat JSON-a s istim informacijama koje ste zatražili. Ne morate se baviti filtriranjem neželjenih informacija ili patite od režijskih troškova zbog velikih odgovora.
Što je REST API?
Pa, REST je kratica za Reprezentativni državni prijenos, a API je sučelje za programiranje aplikacija. REST API ili API "RESTful" postao je temeljna filozofija dizajna iza većine modernih aplikacija klijent-poslužitelj. Ideja proizlazi iz potrebe za odvajanjem različitih komponenata aplikacije poput korisničkog sučelja na strani klijenta i logike na strani poslužitelja.
Dakle, sesija između klijenta i poslužitelja obično je bez državljanstva. Nakon što se web stranica i povezane skripte učitaju, možete nastaviti interakciju s njima, a kada izvršite radnju (poput pritiska gumba za slanje), šalje se zahtjev za slanjem zajedno sa svim kontekstualnim informacijama koje web poslužitelj treba za obradu tog zahtjeva ( poput korisničkog imena, tokena itd.). Aplikacija prelazi iz jednog stanja u drugo, ali bez stalne potrebe za vezom između klijenta i poslužitelja.
REST definira skup ograničenja između klijenta i poslužitelja, a komunikacija se može dogoditi samo pod tim ograničenjima. Na primjer, REST preko HTTP-a obično koristi model CRUD, što je skraćenica za Stvaranje, čitanje, ažuriranje i brisanje, a HTTP metode poput POST, GET, PUT i DELETE pomažu vam u izvođenju tih operacija i tih operacija same. Stare tehnike upada poput SQL injekcija nisu mogućnost s nečim poput čvrsto napisanog REST API-ja (iako REST nije sigurnosna panaceja).
Također jako pomaže programerima korisničkog sučelja! Budući da sve što primite od HTTP zahtjeva tipičan je tok teksta (ponekad formatiran kao JSON), lako možete implementirati web stranicu za preglednike ili aplikaciju (na vašem željenom jeziku) bez brige o arhitekturi na strani poslužitelja. Pročitali ste API dokumentaciju za usluge kao što su Reddit, Twitter ili Facebook i možete napisati proširenja za njih ili klijente treće strane na jeziku po vašem izboru jer vam je zajamčeno da će ponašanje API-ja i dalje biti isto.
Suprotno tome, poslužitelja nije briga je li prednji kraj napisan u Go, Ruby ili Python. Bez obzira radi li se o pregledniku, aplikaciji ili CLI-u. Samo 'vidi' zahtjev i odgovara na odgovarajući način.
Što je GraphQL?
Kao i bilo što u svijetu računala, REST API-ji postali su veći i složeniji, a ljudi su ih istodobno željeli implementirati i trošiti na brži i jednostavniji način. Zbog toga je Facebook došao na ideju GraphQL-a i kasnije ga otvorio. QL u GraphQL-u označava jezik upita.
GraphQL omogućuje klijentima da daju vrlo specifične API zahtjeve, umjesto da upućuju krute API pozive s unaprijed definiranim parametrima i odgovorima. Puno je jednostavnije jer poslužitelj tada odgovara točno podacima koje ste tražili, bez ičega viška.
Pogledajte ovaj REST zahtjev i njegov odgovarajući odgovor. Ovaj je zahtjev namijenjen samo javnoj biografiji korisnika.
Zahtjev: GET https: // api.github.com / users /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 / oktobar ",
"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 / sa zvjezdicom / owner / repo ",
"subscriptions_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": "Korisnik",
"site_admin": netačno,
"name": "Oktokat",
"company": "GitHub",
"blog": "http: // www.github.com / blog ",
"location": "San Francisco",
"email": null,
"hireable": null,
"bio": null,
"public_repos": 8,
"public_gists": 8,
"sljedbenici": 2455,
"slijedeći": 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Koristio sam korisničko ime octocat, ali možete ga zamijeniti korisničkim imenom po vašem izboru i upotrijebite cURL za upućivanje ovog zahtjeva u naredbeni redak ili Poštara ako vam je potreban GUI. Iako je zahtjev bio jednostavan, razmislite o svim dodatnim informacijama koje dobivate iz ovog odgovora. Ako biste obrađivali podatke od milijun takvih korisnika i filtrirali sve nepotrebne podatke, to nije učinkovito. Trošite propusnost, memoriju i računanje u dobivanju, spremanju i filtriranju svih milijuna dodatnih parova ključ / vrijednost koje nikada nećete
Također struktura odgovora nije nešto što znate unaprijed. Ovaj JSON odgovor ekvivalentan je rječničkom objektu u Pythonu ili objektu u JavaScript-u. Ostale krajnje točke odgovarat će JSON objektima koji se mogu sastojati od ugniježđenih objekata, ugniježđenog popisa unutar objekta ili bilo koje proizvoljne kombinacije tipova podataka JSON, a morat ćete uputiti dokumentaciju da biste dobili detalje. Kada obrađujete zahtjev, morate biti svjesni ovog formata koji se mijenja od krajnje točke do krajnje točke.
GraphQL se ne oslanja na HTTP glagole poput POST, GET, PUT i DELETE za izvođenje CRUD operacija na poslužitelju. Umjesto toga, postoji samo jedna vrsta HTTP zahtjeva i endopint za sve operacije povezane s CRUD-om. U slučaju GitHub-a to uključuje zahtjeve tipa POST sa samo jednom krajnjom točkom https: // api.github.com / graphql
Budući da je POST zahtjev, sa sobom može nositi tekst poput JSON-a kroz koji će biti naše GraphQL operacije. Te operacije mogu biti tipaa upit ako sve što želi jest pročitati neke informacije ili to može biti mutacija u slučaju da podatke treba modificirati.
Da biste uputili GraphQL API pozive, možete koristiti GitHub-ov GraphQL Explorer. Pogledajte ovaj GraphQL upit za dohvaćanje iste vrste podataka (korisnikova javna biografija) kao što smo to učinili gore koristeći REST.
Zahtjev: POST https: // api.github.com / graphqlupit
korisnik (prijava: "ranvo")
bio
Odgovor:
"podaci":
"korisnik":
"bio": "Ljubitelji tehnike i znanosti. Bavim se svim vrstama nepovezanih stvari iz
poslužitelji za kvantnu fiziku.\ r \ nPovremeno pišem postove na blogu o gore navedenim interesima."
Kao što vidite, odgovor se sastoji samo od onoga što ste tražili, to je biografija korisnika. Odaberete određenog korisnika prosljeđivanjem korisničkog imena (u mom slučaju to je ranvo), a zatim tražite vrijednost atributa tog korisnika, u ovom slučaju taj atribut je bio. API poslužitelj traži točno određene podatke i odgovara time i ničim drugim.
S druge strane, GraphQL vam također omogućuje da podnesete jedan zahtjev i izvučete informacije koje bi vam trebale više zahtjeva u tradicionalnom REST API-ju. Sjetimo se da su svi GraphQL zahtjevi upućeni samo na jednu API krajnju točku. Uzmimo za primjer slučaj upotrebe u kojem trebate pitati GitHub API poslužitelj za biografiju korisnika i jedan od njegovih SSH ključeva. Bila bi potrebna dva GET zahtjeva.
ODMORNI zahtjevi: GET https: // api.github.com /DOBITI https: // api.github.com /
Zahtjev za GraphQL: POST https: // api.github.com / graphql /
upit
korisnik (prijava: "ranvo")
bio
publicKeys (zadnji: 1)
rubovi
čvor
ključ
Odgovor GraphQL-a:
"podaci":
"korisnik":
"bio": "Ljubitelji tehnike i znanosti. Bavim se svim vrstama nepovezanih stvari iz
poslužitelji kvantne fizike.\ r \ nPovremeno pišem postove na blogu o gore navedenim interesima.",
"publicKeys":
"rubovi": [
"čvor":
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Postoje ugniježđeni objekti, ali ako pogledate vaš zahtjev, oni se poprilično podudaraju s vašim zahtjevom, tako da možete znati i u nekom smislu oblikovati strukturu odgovora koji dobijete .
Zaključak
GraphQL dolazi s vlastitom krivuljom učenja, koja je vrlo strma ili uopće nije strma, ovisno o tome koga pitate. S objektivnog stajališta mogu vam predstaviti sljedeće činjenice. Fleksibilan je kao što ste vidjeli gore, introspektivan je - to jest, možete pitati GraphQL API o samom API-u. Čak i ako nećete graditi svoj API poslužitelj pomoću njega, velika je vjerojatnost da ćete se morati povezati s API-jem koji omogućuje samo GraphQL.
Ovdje možete saznati nešto više o njenim tehničkim karakteristikama, a ako želite uputiti GraphQL API pozive sa svoje lokalne radne stanice, tada upotrijebite Graphiql.
