Sofa - Den beste måten å REST (er GraphQL)

Avslutter REST vs GraphQL-debatten en gang for alle

Aktiver REST API på et øyeblikk

TL; DR

  • Ikke velg mellom REST og GraphQL - opprett et fullstendig RESTful API automatisk fra GraphQL-implementeringen (med et bibliotek og en enkelt kodelinje)
  • Få de fleste fordelene med GraphQL på backend og frontend, mens du bruker og utsetter REST
  • Støtt alle dine eksisterende klienter med REST mens du forbedrer backend-stabelen din med GraphQL
  • Lag egendefinerte, perfekt klientjusterte REST-sluttpunkter for frontend ganske enkelt ved å navngi en rute og legge ved en spørring
  • Slutt å krangle om REST vs GraphQL. Bruk GraphQL, generer REST og få det beste ut av begge
  • På den andre måten (REST til GraphQL) får du ikke det beste fra begge verden, men mindre kraftig, vanskeligere å opprettholde serverimplementering med noen av fordelene med GraphQL. Det er en god og rask start for en migrasjon ..

Vent, HVA !?

Det er skrevet mange artikler om fordeler og ulemper ved GraphQL og REST API og hvordan du bestemmer hvilken du skal bruke. Jeg har ikke tenkt å gjenta de her ..

Mye tid og energi brukt av smarte konsulenter på å skrive disse artiklene, les disse artiklene, mens de fleste av dem er ferdige med "det avhenger av din brukssak" -sammendrag, uten å spesifisere disse brukssakene!

Jeg har jobbet med REST, GraphQL og SOAP APIer i mange år. Så jeg tenkte, hvorfor ikke komme med en liste over disse brukssakene og for hver enkelt av dem å sjekke - hva kan du ikke gjøre i GraphQL som du kan gjøre med REST og hva du ikke vil gjøre med GraphQL og du foretrekker REST.

Etter å ha opprettet den listen, hadde jeg plutselig en tanke - hva hvis det var et annet alternativ - hva hvis min kraftige GraphQL-server bare kunne generere et REST API for meg?

Da kunne jeg få det beste fra begge verdener!

Jo mer jeg dykket inn i ideen og implementeringen, desto mer innså jeg at det ikke bare er at vi kan ha begge typer APIer laget for oss, men selv om vi bare vil eksponere REST APIer, og ingen av kundene våre bruker GraphQL, er GraphQL beste måten å opprette REST APIer!

Hvordan gir setningen ovenfor til og med mening?

Vanligvis når vi (The Guild) hjelper selskaper og organisasjoner med å modernisere APIene sine, er de første som forstår fordelene med GraphQL frontend-utviklerne, av åpenbare grunner. Men så snart backend-utviklerne “Få det”, blir de teknologiens største talsmenn. Men de trenger fortsatt å støtte eksisterende kunder og tredjepartspartnere.

Derfor får de nylig genererte REST API-ene mange funksjoner og fordeler fra den interne GraphQL-implementeringen som gjør backend-utviklere glade:

  • Fullt generert dokumentasjon som alltid er oppdatert (Swagger, OpenAPI og GraphiQL)
  • Virkelig RESTful API ut av boksen
  • GraphQL-abonnement som nettkroker
  • Validering av data på kort tid - være 100% sikker på at hentet data samsvarer med skjemaets og spørringens struktur. Du sender nøyaktig det jeg vil sende, streng er en streng, et objekt har nøyaktig de samme egenskapene.
  • Å opprette et tilpasset sluttpunkt handler nå om å velge et rutenavn og knytte en spørring til det. gjort. Ikke mer manuelt arbeid med å lage og vedlikeholde kundespesifikke sluttpunkter!
  • Bruk GraphQLs filosofi om å utvikle APIer gjennom skjemaer - ikke mer smertefulle V1 - V2 API-migrasjoner.
  • Bruk moderne teknologi som er lettere å ansette folk til. Selskaper som Facebook, Airbnb og andre har flyttet til GraphQL. Ingen av dem har gått tilbake.
  • Kraften til GraphQL-oppløsere til å lage din API-implementering, i stedet for manuelt skrevne kontrollere fra MVC

Hva får jeg av å ha oppløsere?

  • Enklere å transformere data slik at de samsvarer med responsen (GraphQL Schema). Det er fordi hver enhet har sine egne oppløsere, så kartleggingen flyttes i mindre biter og gjenbrukes på tvers av en hel app.
  • GraphQL lar deg enkelt dele data på tvers av hver resolver, vi kaller det Context.
  • Tvinger deg til å definere og løse data på en meningsfull måte som faktisk er med på å bygge et API. Den kjører funksjoner parallelt (funksjoner som er nestet på samme nivå), håndterer async og til slutt er det ansvarlig for å slå sammen alt dette til et enkelt objekt, så du trenger ikke å tenke på det.

Sofa - Bruk GraphQL til å lage RESTful APIer

Så vi opprettet Sofa (ordspill ment), et åpen kildekode-bibliotek du installerer på GraphQL-serveren for å lage en fullstendig RESTful og konfigurerbar API-gateway. Bruk GraphQL for å RESTE.

“Hvordan” -opplæringen

La oss lage en kort trinnvis veiledning om hvordan du oppretter et RESTful API.

Trinn 1: npm installer pakken `sofa-api` og legg til følgende kodelinje:

Trinn 2: Gå REST på en sofa, du er ferdig.

Kamil Kisiela la Sofa til implementeringen av SpaceX GraphQL API av Carlos Rufo, i en enkelt forpliktelse.

Sjekk ut de fullstendig genererte REST-endepunktene, Swagger live-dokumentasjonen, GraphiQL-editoren og GraphiQL-Explorer!

For øvrig, det du ser her er et REST API, generert på toppen av et GraphQL API, opprettet på toppen av et annet REST API….

Hvorfor gjorde du det for!?!?

Migrer gradvis fra gamle REST implementeringer

Dette er faktisk en god retning å gå. I mange av selskapene vi jobber med, har de laget REST API-lag ved å bruke gammel teknologi på toppen av sine originale web-tjenester.

Men disse REST-implementeringene er problematiske (av alle de åpenbare grunnene til at folk velger å flytte til GraphQL).

Så vår vei å gå er å lage GraphQL-implementeringer på toppen av disse REST-lagene, migrere klientene til implementeringene og deretter gradvis fjerne det gamle RESTful-laget og ringe tjenestene direkte.

Å bruke Sofa gjorde disse overgangene mye raskere fordi vi kan tilby alle eksisterende kunder å migrere til GraphQL-implementeringen uten å bruke GraphQL selv. Vi utsetter ganske enkelt de samme REST-endepunktene på toppen av GraphQL, og de beveger seg lykkelig til laget vårt fordi vi kan imøtekomme alle forespørsler og tilpassede REST-endepunkter mye raskere enn de originale, gamle REST-implementeringene.

Gi meg flere detaljer

Sofa bruker Express som standard, men du kan bruke ethvert annet serverrammeverk. Sofa er også agnostisk for implementering av GraphQL server.

Gå over til Sofa-nettstedet for dokumentasjon og til Github-depot for rapportering av problemer og hjelp.

Hvordan sofa fungerer?

Under panseret gjør Sofa hvert felt av spørrings- og mutasjonstyper til ruter. Første gruppe ruter er bare tilgjengelig via GET-metoden, mutasjoner på den annen side får POST.

Sofa bruker GraphQLs AST for å opprette en operasjon med alle mulige variabler (også de som er dypt nestet) og vet nøyaktig hva jeg skal hente. Senere konverterer den forespørselsorganet til driftsvariabler og kjører den mot skjemaet. Det skjer lokalt, men det er også mulig å bruke en ekstern GraphQL Server eller til og med Apollo Link.

Akkurat nå har Sofa en innebygd støtte for Express, men det er fullt mulig å bruke et annet rammeverk. Hovedkonseptet forblir nøyaktig det samme, slik at bare måten vi håndterer forespørselen på, er forskjellige på forskjellige serverimplementeringer.

GraphQL-abonnement som nettkroker?

Slik det fungerer er ganske enkelt, du starter et abonnement ved å ringe en spesiell rute og du får en unik ID som senere kan brukes til å oppdatere eller til og med stoppe abonnementet. Abonnement er Webhooks. Sofa vet nøyaktig når det er en jevn hendelse på APIen din og varsler deg gjennom endepunktet du har tildelt et abonnement på.

Modeller / ressurser?

I noen tilfeller vil du ikke eksponere et helt objekt, men bare dets ID. Hvordan kan du gjøre det med Sofa? Du må ha to spørsmål. Først må man returnere en enkelt enhet basert bare på ID-en (som vil være et argument), og den andre bør løse en liste over disse. Navnene skal også samsvare, for eksempel en ressurs som heter Bruker, skal ha to spørsmål: bruker (id: ID): Bruker og brukere: [Bruker]. Stort sett den samme tingen du ville gjort med REST.

type spørring {
  bruker (id: ID!): Bruker
  brukere: [Bruker]
}

Før Sofa lager rutene, ser den etter disse modellene og registrerer dem, så når operasjonene er bygget, henter du ikke alt, men bare en ID.

Men hva hvis du vil hente et helt objekt, men bare noen få steder?

Det er et alternativ som heter ignorere som lar deg gjøre det. Du passerer ganske enkelt en bane der du vil overskrive standardoppførselen.

Gitt skjemaet nedenfor, vil du få bare forfatter-ID.

type bok {
  jeg gjorde
  tittel: String!
  forfatter: bruker!
}
utvide type spørring {
  bok (id: ID!): Bok
  bøker: [Bok]
}

Med ignorere: ['Book.author'] ender du opp med et helt brukerobjekt.

sofa({
  ...,
  ignorere: ['Book.author'],
})

Swagger og OpenAPI

Takket være GraphQLs typesystem kan Sofa generere alltid oppdatert dokumentasjon for REST API. Akkurat nå støtter vi Swagger og OpenAPI-spesifikasjonen, men det er veldig enkelt å ta i bruk forskjellige spesifikasjoner.

Sammendrag

sofa-api gjør det ekstremt enkelt å lage et RESTful API med all den beste praksis for REST fra en GraphQL-server ved å bruke all sin kraft.

Slutt å kaste bort livet ditt med å krangle om REST vs GraphQL - Vær produktiv, få fordelene fra begge verdener og gå inn i fremtiden for API-utvikling.

Jeg håper dette ville bli den siste REST vs. GraphQL-artikkelen der ute…. Hvis du tror det ikke vil, kan du kommentere med en brukssak og la oss prøve det!

Takk til Kamil Kisiela for å ha jobbet med meg på dette og gjort dette biblioteket til virkelighet!

Følg oss på GitHub og Medium, vi planlegger å gi ut mange flere innlegg de neste par ukene om hva vi har lært ved hjelp av GraphQL de siste årene.