Sofa - De beste manier om te RUSTEN (is GraphQL)

Het REST vs GraphQL-debat voor eens en altijd beëindigen

Activeer REST API in een handomdraai

TL; DR

  • Kies niet tussen REST en GraphQL - maak automatisch een volledig RESTful API vanuit uw GraphQL-implementatie (met een bibliotheek en een enkele coderegel)
  • Krijg de meeste voordelen van GraphQL op de backend en frontend, terwijl u REST gebruikt en blootlegt
  • Ondersteun al uw bestaande klanten met REST en verbeter tegelijkertijd uw backend-stack met GraphQL
  • Maak aangepaste, perfect klantgerichte REST-eindpunten voor uw frontend door eenvoudig een route een naam te geven en een query toe te voegen
  • Stop met ruzie over REST versus GraphQL. Gebruik GraphQL, genereer REST en haal het beste uit beide
  • Omgekeerd (REST to GraphQL) krijgt u niet het beste van beide wereld, maar minder krachtig, moeilijker om serverimplementatie te onderhouden met enkele voordelen van GraphQL. Het is echter een goede en snelle start voor een migratie ..

Wacht wat!?

Er zijn veel artikelen geschreven over de voor- en nadelen van GraphQL en REST API's en hoe te beslissen welke te gebruiken. Ik ga die hier niet herhalen ...

Veel tijd en energie besteed door slimme consultants om die artikelen te schrijven, die artikelen te lezen, terwijl de meeste zijn afgewerkt met de samenvatting "het hangt af van uw use case", zonder die use cases daadwerkelijk te specificeren!

Ik werk al vele jaren met REST-, GraphQL- en SOAP-API's. Dus ik dacht, waarom zou je niet een lijst maken van die use cases en voor elk daarvan om te controleren - wat kun je niet doen in GraphQL dat je kunt doen met REST en wat je niet zou willen doen met GraphQL en u geeft de voorkeur aan REST.

Nadat ik die lijst had gemaakt, dacht ik plotseling - wat als er een andere optie was - wat als mijn krachtige GraphQL-server gewoon een REST API voor mij zou kunnen genereren?

Dan kon ik het beste van beide werelden krijgen!

Hoe meer ik in het idee en de implementatie dook, hoe meer ik besefte dat het niet alleen is dat we beide soorten API's voor ons kunnen laten maken, maar zelfs als we alleen REST API's willen onthullen en geen van onze klanten GraphQL gebruikt, is GraphQL de beste manier om de REST API's te maken!

Hoe is bovenstaande zin zinvol ?!

Wanneer wij (The Guild) bedrijven en organisaties helpen hun API's te moderniseren, zijn de frontend-ontwikkelaars om voor de hand liggende redenen de eersten die de voordelen van GraphQL begrijpen. Maar zodra de backend-ontwikkelaars het “krijgen”, worden ze de grootste voorstanders van de technologie. Maar ze moeten nog steeds bestaande klanten en externe partners ondersteunen.

Daarom krijgen die nieuw gegenereerde REST API's veel van de functies en voordelen van de interne GraphQL-implementatie die backend-ontwikkelaars blij maken:

  • Volledig gegenereerde documentatie die altijd up-to-date is (Swagger, OpenAPI en GraphiQL)
  • Echt RESTful API uit de doos
  • GraphQL-abonnementen als Webhooks
  • Runtime-validatie van gegevens: wees 100% zeker dat de opgehaalde gegevens overeenkomen met de structuur van het schema en de query. U verzendt precies wat ik wil verzenden, string is een string, een object heeft exact dezelfde eigenschappen.
  • Het maken van een aangepast eindpunt is nu een kwestie van een routenaam kiezen en er een query aan koppelen. gedaan. Geen handmatig werk meer om klantspecifieke eindpunten te maken en te onderhouden!
  • Gebruik de filosofie van GraphQL om API's te ontwikkelen via schema's - geen pijnlijke V1 - V2 API-migraties meer.
  • Gebruik moderne technologie die gemakkelijker is om mensen aan te werven. Bedrijven zoals Facebook, Airbnb en anderen zijn verhuisd naar GraphQL. Geen van hen is teruggegaan.
  • De kracht van GraphQL-resolvers om uw API-implementatie te maken, in plaats van handmatig geschreven controllers van MVC

Wat krijg ik als ik resolvers heb?

  • Gemakkelijker om gegevens te transformeren zodat deze overeenkomen met het antwoord (GraphQL-schema). Dat komt omdat elke entiteit zijn eigen resolvers heeft, dus de toewijzing wordt in kleinere stukken verplaatst en opnieuw gebruikt in een hele app.
  • Met GraphQL kunt u eenvoudig gegevens delen met elke resolver, we noemen het context.
  • Dwingt u om gegevens op een eigenzinnige manier te definiëren en op te lossen die daadwerkelijk helpt bij het bouwen van een API. Het voert functies parallel uit (functies die op hetzelfde niveau zijn genest), verwerkt asynchroon en uiteindelijk is het verantwoordelijk voor het samenvoegen van dat alles in een enkel object, dus u hoeft er niet aan te denken.

Sofa - Gebruik GraphQL om RESTful API's te maken

Daarom hebben we Sofa (bedoelde woordspeling) gemaakt, een open source-bibliotheek die u op uw GraphQL-server installeert om een ​​volledig RESTful en configureerbare API-gateway te maken. Gebruik GraphQL om te RUSTEN.

"How to" tutorial

Laten we een korte stapsgewijze zelfstudie maken over het maken van een RESTful API.

Stap 1: npm installeer het `sofa-api`-pakket en voeg de volgende coderegel toe:

Stap 2: RUST op een bank, je bent klaar.

Kamil Kisiela voegde Sofa toe aan de SpaceX GraphQL API-implementatie door Carlos Rufo, in een enkele commit.

Bekijk de volledig gegenereerde REST-eindpunten, de Swagger live documentatie, GraphiQL-editor en de GraphiQL-Explorer!

Trouwens, wat je hier ziet, is een REST API, gegenereerd bovenop een GraphQL API, gemaakt bovenop een andere REST API….

Waarom deed je dat voor!?!?

Geleidelijk migreren van oude REST-implementaties

Dit is eigenlijk een goede richting om te gaan. In veel van de bedrijven waarmee we samenwerken, hebben ze REST API-lagen gemaakt met behulp van oude technologie bovenop hun oorspronkelijke webservices.

Maar die REST-implementaties zijn problematisch (om alle voor de hand liggende redenen kiezen mensen ervoor om naar GraphQL te gaan).

Dus onze manier om te gaan is door GraphQL-implementaties bovenop die REST-lagen te maken, de clients naar die implementaties te migreren en vervolgens geleidelijk de oude RESTful-laag te verwijderen en de services rechtstreeks aan te roepen.

Het gebruik van Sofa maakte die overgangen veel sneller omdat we alle bestaande clients kunnen aanbieden om naar onze GraphQL-implementatie te migreren zonder GraphQL zelf te gebruiken. We stellen eenvoudig dezelfde REST-eindpunten bovenop GraphQL bloot en ze gaan graag naar onze laag omdat we al hun verzoeken en aangepaste REST-eindpunten veel sneller kunnen verwerken dan de originele, oude REST-implementaties.

Geef me meer details

Sofa gebruikt standaard Express, maar u kunt elk ander serverframework gebruiken. Sofa is ook GraphQL-serverimplementatie agnostisch.

Ga naar de Sofa-website voor documentatie en naar de Github-repository voor het melden van problemen en het helpen.

Hoe werkt Sofa?

Onder de motorkap verandert Sofa elk veld van Query- en mutatietypes in routes. Eerste groep routes is alleen beschikbaar via de GET-methode, mutaties krijgen daarentegen POST.

Sofa gebruikt GraphQL's AST om een ​​bewerking te maken met alle mogelijke variabelen (zelfs die diep genest) en weet precies wat te halen. Later zet het de body van het verzoek om in de variabelen van de operatie en voert het uit tegen het schema. Het gebeurt lokaal, maar het is ook mogelijk om een ​​externe GraphQL-server of zelfs Apollo Link te gebruiken.

Op dit moment heeft Sofa een ingebouwde ondersteuning voor Express, maar het is heel goed mogelijk om een ​​ander framework te gebruiken. Het hoofdconcept blijft exact hetzelfde, dus alleen de manier waarop we het verzoek behandelen, verschilt per serverimplementatie.

GraphQL-abonnementen als Webhooks?

De manier waarop het werkt is eenvoudig: u start een abonnement door een speciale route te bellen en u krijgt een unieke ID die later kan worden gebruikt om het abonnement bij te werken of zelfs te stoppen. Abonnementen zijn Webhooks. Sofa weet precies wanneer er een gebeurtenis gebeurt op uw API en waarschuwt u via het eindpunt waaraan u een abonnement hebt toegewezen.

Modellen / middelen?

In sommige gevallen wilt u niet een volledig object blootleggen, maar alleen de id. Hoe kun je dat met Sofa doen? U moet twee vragen hebben. Eerst moet een enkele entiteit worden geretourneerd op basis van alleen zijn id (wat een argument zou zijn) en de tweede moet een lijst met die oplossen. De namen moeten ook overeenkomen, bijvoorbeeld een bron met de naam Gebruiker moet twee query's hebben: gebruiker (id: ID): Gebruiker en gebruikers: [Gebruiker]. Vrijwel hetzelfde als wat u zou doen met REST.

type zoekopdracht {
  user (id: ID!): User
  gebruikers: [gebruiker]
}

Voordat Sofa de routes maakt, zoekt het naar die modellen en registreert ze, dus wanneer de bewerkingen zijn gebouwd, haalt u niet alles op, maar alleen een ID.

Maar wat als u een volledig object wilt ophalen, maar slechts op enkele plaatsen?

Er is een optie genaamd negeren waarmee je dat kunt doen. U passeert eenvoudig een pad waarin u het standaardgedrag wilt overschrijven.

Gezien het onderstaande schema, zou u alleen het ID van de auteur krijgen.

type Boek {
  ik deed
  titel: String!
  auteur: Gebruiker!
}
type zoekopdracht uitbreiden {
  book (id: ID!): Book
  boeken: [Boek]
}

Met negeren: ['Book.author'] krijgt u een volledig gebruikersobject.

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

Swagger en OpenAPI

Dankzij het type systeem van GraphQL kan Sofa altijd actuele documentatie genereren voor uw REST API. Op dit moment ondersteunen we Swagger en zijn OpenAPI-specificatie, maar het is heel eenvoudig om verschillende specificaties aan te nemen.

Samenvatting

sofa-api maakt het uiterst eenvoudig om een ​​RESTful API te maken met alle best practices van REST vanaf een GraphQL-server met al zijn kracht.

Verspil geen leven meer aan ruzie over REST versus GraphQL - Wees productief, profiteer van de voordelen van beide werelden en ga op weg naar de toekomst van API-ontwikkeling.

Ik hoop dat dit het laatste REST versus GraphQL-artikel wordt dat er is…. als je denkt dat het niet lukt, reageer dan met een use case en laten we het proberen!

Dank aan Kamil Kisiela voor het samenwerken met mij en het tot stand brengen van deze bibliotheek!

Volg ons op GitHub en Medium, we zijn van plan om de komende weken nog veel meer berichten uit te brengen over wat we de afgelopen jaren hebben geleerd met GraphQL.