TL; DR -versjon

I et av de forrige innleggene diskuterte vi i korte trekk hvordan det er å bruke GitHub API V3. Denne versjonen er designet for å bli koblet sammen som alle andre REST API. Det er endepunkter for hver ressurs du trenger å få tilgang til og/eller endre. Det er endepunkter for hver bruker, hver organisasjon, hvert depot og så videre. For eksempel har hver bruker sitt API -endepunkt på https: // API.github.com/ brukere/ du kan prøve å erstatte brukernavnet ditt i stedet for og angi URL -en i en nettleser for å se hva API svarer med.

GitHub API V4 bruker derimot GraphQL der QL står for spørringsspråk. GraphQL er en ny måte å designe APIene dine på. Akkurat som det er mange webtjenester som tilbys som REST API -er, ikke bare de som tilbys av GitHub, er det mange webtjenester som lar deg grensesnitt med dem via GraphQL.

Den sterkeste forskjellen du vil legge merke til mellom GraphQL og REST API er at GraphQL kan fungere av et enkelt API -endepunkt. I tilfelle av GitHub API V4, er dette sluttpunktet https: // API.github.com/graphql og det er det. Du trenger ikke å bekymre deg for å legge til lange strenger på slutten av en Root URI eller levere en spørringsstrengparameter for ekstra informasjon. Du sender ganske enkelt et JSON -lignende argument til dette API, og ber bare om tingene du trenger, og du vil få en JSON -nyttelast tilbake med nøyaktig samme informasjon som du ba om. Du trenger ikke å takle filtrering av uønsket informasjon, eller lider av ytelsesoverhead på grunn av store svar.

Hva er REST API?

Vel, hvile står for Representational State Transfer og API står for applikasjonsprogrammeringsgrensesnitt. Et REST API, eller et 'RESTFUL' API, har blitt kjernedesign-filosofien bak de fleste moderne klient-server-applikasjoner. Ideen kommer frem fra behovet for å skille forskjellige komponentene i en applikasjon som kundesiden UI og serversiden Logic.

Så økten mellom en klient og en server er typisk statsløs. Når websiden og relaterte skript er lastet inn, kan du fortsette å samhandle med dem, og når du utfører en handling (som Trykk på en send -knapp), sendes en sendforespørsel sammen med all kontekstuell informasjon som webserveren trenger for å behandle den forespørselen ( som brukernavn, symboler osv.). Applikasjonen overgår fra en tilstand til en annen, men uten et konstant behov for forbindelse mellom klienten og serveren.

Rest definerer et sett med begrensninger mellom klienten og serveren, og kommunikasjonen kan bare skje under disse begrensningene. For eksempel hviler REST over HTTP vanligvis CRUD -modellen, som står for å lage, lese, oppdatere og slette og HTTP -metoder som Post, Get, Sett og slett hjelp til å utføre disse operasjonene og de operasjonene alene. Gamle inntrengingsteknikker som SQL -injeksjoner er ikke en mulighet med noe som et tett skrevet REST API (selv om det er hvile er ikke et sikkerhetsperson).

Det hjelper også UI -utviklere ganske mye! Siden alt du mottar fra en HTTP -forespørsel er typisk en strøm av tekst (formatert som JSON, noen ganger) kan du enkelt implementere en webside for nettlesere eller en app (på det foretrukne språket) uten å bekymre deg for serversidearkitektur. Du leser API-dokumentasjonen for tjenester som Reddit, Twitter eller Facebook, og du kan skrive utvidelser for dem eller tredjepartsklienter på språket du velger, siden du er garantert at oppførselen til API fremdeles vil være den samme.

Motsatt bryr serveren seg ikke om frontend er skrevet i Go, Ruby eller Python. Enten det er en nettleser, app eller en CLI. Den ser bare 'forespørselen og svarer på riktig måte.

Hva er grafql?

Som med alt i datamaskinens verden, ble REST API -er større og mer sammensatt, og samtidig ønsket folk å implementere og konsumere dem på en raskere og enklere måte. Dette er grunnen til at Facebook kom på ideen om GraphQL, og senere åpnet den. QL i GraphQL står for spørringsspråk.

GraphQL lar klienter komme med veldig spesifikke API -forespørsler, i stedet for å ringe stive API -anrop med forhåndsdefinerte parametere og svar. Det er mye enklere fordi serveren deretter svarer med nøyaktig dataene du ba dem om, uten noe overskudd.

Ta en titt på denne hvileforespørselen og den tilsvarende responsen. Denne forespørselen er ment å se bare en brukers offentlige bio.

Forespørsel: Få https: // API.github.com/brukere/
Respons:

"Logg inn": "Octocat",
"ID": 583231,
"node_id": "mdq6vxnlcju4mzizmq ==",
"avatar_url": "https: // avatars3.GitHubUserContent.com/u/583231?v = 4 ",
"gravatar_id": "",
"URL": "https: // api.github.com/brukere/octocat ",
"html_url": "https: // github.com/octocat ",
"følgere_url": "https: // api.github.com/brukere/octocat/følgere ",
"følgende_url": "https: // api.github.com/brukere/octocat/følgende /other_user ",
"gists_url": "https: // api.github.com/brukere/octocat/gists /gist_id ",
"Starred_url": "https: // api.github.com/brukere/octocat/stjerne /eier /repo ",
"abonnements_url": "https: // api.github.com/brukere/octocat/abonnement ",
"Organisasjoner_url": "https: // API.github.com/brukere/octocat/orgs ",
"repos_url": "https: // api.github.com/brukere/octocat/repos ",
"Events_url": "https: // api.github.com/brukere/octocat/hendelser /personvern ",
"mottatt_events_url": "https: // api.github.com/brukere/octocat/mottatte_eventer ",
"Type": "Bruker",
"Site_admin": False,
"Navn": "The Octocat",
"Company": "GitHub",
"Blogg": "http: // www.github.com/blogg ",
"Sted": "San Francisco",
"E -post": NULL,
"ansettbar": null,
"Bio": NULL,
"public_repos": 8,
"Public_gists": 8,
"Følgere": 2455,
"Følgende": 9,
"CATED_AT": "2011-01-25T18: 44: 36Z",
"Oppdatert_at": "2018-11-22T16: 00: 23z"

Jeg har brukt brukernavnet Octocat, men du kan erstatte den med brukernavnet du ønsker og bruke Curl for å komme med denne forespørselen i kommandolinjen eller postbudet hvis du trenger en GUI. Mens forespørselen var enkel, kan du tenke på all den ekstra informasjonen du får fra dette svaret. Hvis du skulle behandle data fra en million slike brukere og filtrere ut alle unødvendige data som bruker, er det ikke effektivt. Du kaster bort båndbredde, minne og beregner i å få, lagre og filtrere bort alle millioner ekstra nøkkelverdipar som du aldri vil deg

Også strukturen i responsen er ikke noe du vet på forhånd. Denne JSON -responsen tilsvarer ordbokobjekt i Python, eller et objekt i JavaScript. Andre endepunkter vil svare med JSON -objekter som kan være sammensatt av nestede objekter, nestede liste i objektet eller en hvilken som helst vilkårlig kombinasjon av JSON -datatyper, og du må henvise til dokumentasjonen for å få detaljene. Når du behandler forespørselen, må du være klar over dette formatet som endres fra endepunkt til endepunkt.

GraphQL er ikke avhengige av HTTP -verb som Post, Få, satt og sletter for å utføre CRUD -operasjoner på serveren. I stedet er det bare en type HTTP -forespørselstype og endopint for alle CRUD -relaterte operasjoner. I tilfelle av github innebærer dette forespørsler om type innlegg med bare ett endepunkt https: // API.github.com/grafql

Å være en postforespørsel kan ha med seg en JSON -lignende tekst som vil være vår GraphQL -operasjoner. Disse operasjonene kan være av typa spørsmål Hvis alt det vil gjøre er å lese litt informasjon, eller det kan være en mutasjon I tilfelle data må endres.

For å gjøre GraphQL API -samtaler kan du bruke GitHubs GraphQL Explorer. Ta en titt på denne grafql spørsmål å hente den samme typen data (en brukers offentlige biograf) som vi gjorde ovenfor ved hjelp av hvile.

Forespørsel: Legg ut https: // API.github.com/grafql
spørsmål
bruker (pålogging: "ranvo")
Bio


Respons:

"Data":
"Bruker":
"Bio": "Tekniske og vitenskapelige entusiaster. Jeg er inne på alle slags ikke -relaterte ting fra
servere til kvantefysikk.\ r \ noCcasionally, jeg skriver blogginnlegg om ovennevnte interesser.""

Som du kan se, består responsen bare av det du ba om, det er brukerens bio. Du velger en bestemt bruker ved å sende brukernavnet (i mitt tilfelle, det er det Ranvo) og så ber du om verdien av en attributt til den brukeren, i dette tilfellet er det attributtet Bio. API -serveren ser opp nøyaktig spesifikk informasjon og svarer med det og ingenting annet.

På baksiden lar GraphQL også deg komme med en enkelt forespørsel og trekke ut informasjon som ville tatt deg flere forespørsler i tradisjonell REST API. Husk at alle GraphQL -forespørsler blir fremsatt til bare ett API -endepunkt. Ta for eksempel brukssaken der du trenger å spørre GitHub API -serveren for brukerens bio og en av SSH -tastene. Det vil kreve to få resquests.

REST -forespørsler: Få https: // API.github.com//
Få https: // API.github.com//nøkler
GraphQL Request: Legg ut https: // API.github.com/graphql/
spørsmål
bruker (pålogging: "ranvo")
Bio
publicKeys (sist: 1)
kanter
Node
nøkkel





GraphQL Response:

"Data":
"Bruker":
"Bio": "Tekniske og vitenskapelige entusiaster. Jeg er inne på alle slags ikke -relaterte ting fra
servere til kvantefysikk.\ r \ noCcasionally, jeg skriver blogginnlegg om ovennevnte interesser."",
"publicKeys":
"Kanter": [

"node":
"Key": "SSH-ED25519 AAAAC3NZAC1LZDI1NTE5AAAAIH31MVJRYDZEH8OD8JVAFPRUIGL65SWILYKPEGBUNGOT"


]

Det er nestet objekt, men hvis du ser på forespørselen din, samsvarer de stort sett forespørselen din slik at du kan vite, og på en eller annen måte, form strukturen til responsen du får .

Konklusjon

GraphQL kommer med sin egen læringskurve, som er veldig bratt, eller ikke bratt i det hele tatt, avhengig av hvem det er at du spør. Fra et objektivt synspunkt kan jeg legge følgende fakta for deg. Det er fleksibelt som du har sett ovenfor, det er introspektivt - det vil si at du kan spørre GraphQL API om API -en selv. Selv om du ikke skal bygge API -serveren din ved å bruke den, er sjansen stor for at du må grensesnitt mot et API som bare tillater GraphQL.

Du kan lære litt mer om dets tekniske forhold her, og hvis du vil ringe GraphQL API -samtaler fra din lokale arbeidsstasjon, så bruk Graphiql.