Ontdek waarom wij aanraden om te integreren via GraphQL in plaats van REST.
Bij Zonos bieden wij twee hoofdtypen API's voor integratie: GraphQL en REST. REST-API's bestaan al langer en zijn voor velen wellicht bekender, maar wij zijn overgestapt op GraphQL om meer flexibiliteit en snellere innovatie mogelijk te maken. Beide worden nog steeds ondersteund, maar deze gids legt uit waarom GraphQL niet alleen de toekomst van onze integraties is, maar ook de toekomst van integraties in het algemeen, en een krachtiger middel om vandaag aan uw behoeften te voldoen.
GraphQL is een alternatieve manier om met API's te communiceren, die zich uitstekend leent voor complexe datastructuren en het bouwen van interfaces daarop. In plaats van data als losse, op zichzelf staande onderdelen te behandelen, laat GraphQL zien hoe databrokken met elkaar samenhangen, waardoor het eenvoudig wordt om informatie op te vragen en te ontvangen.
Zie GraphQL als een querytaal waarmee u met de API communiceert alsof u rechtstreeks met de database praat. Met GraphQL komt u zo dicht mogelijk bij de database, zodat u zelf kunt kiezen welke data u wilt en hoe u die ontvangt, wat een enorm prestatievoordeel oplevert.
GraphQL is ontwikkeld door Facebook om het probleem van schaalbaarheid bij complexe datastructuren op te lossen. Dankzij het succesvolle gebruik ervan zien steeds meer bedrijven de voordelen van GraphQL voor hun API's in.
Kent u REST al? GraphQL zal u bekend voorkomen.
GraphQL-API's zijn eenvoudiger te gebruiken dan u misschien denkt. Als u gewend bent om met REST-API's te werken, ziet u hier hoe de kernconcepten van REST zich vertalen naar GraphQL.
Kenmerk↕
REST↕
GraphQL↕
Eindpunt
Verzoeken gaan naar meerdere eindpunten voor verschillende acties
Alle verzoeken gaan naar één enkel eindpunt (bijv. /graphql)
Data opvragen
Gebruik GET-methoden op specifieke eindpunten om data op te halen
Gebruik queries om precies de benodigde data op te vragen, waardoor over- of under-fetching wordt beperkt
Data wijzigen/acties
Gebruik HTTP-methoden zoals POST, PUT, PATCH of DELETE om data te wijzigen of verwerken.
Gebruik mutations om bewerkingen uit te voeren (bijv. parties aanmaken, landed costs berekenen)
Antwoordformaat
Vaste antwoordformaten retourneren altijd alle voorgedefinieerde velden, ongeacht of ze nodig zijn
Flexibele responses laten u exact aangeven welke velden u wilt ontvangen, wat onnodige gegevensoverdracht beperkt (voelt deze flexibiliteit ingewikkeld, gebruik dan gewoon de kant-en-klare queryvoorbeelden in onze documentatie voor een REST-achtige ervaring)
Dataverbinding
Vaak zijn meerdere verzoeken nodig om gerelateerde data op te halen
Geneste queries maken het mogelijk om gerelateerde data in één verzoek op te halen (bijv. partygegevens en zendingsitems samen). Gebruikers kunnen ook workflows bouwen om meerdere mutations binnen één GraphQL-verzoek te beheren, wat complexiteit vermindert en de efficiëntie verbetert
Voordelen van GraphQL
Snellere responses
GraphQL levert snellere responses dankzij precieze data-opvraging, het gebruik van één enkel eindpunt en verbeterde mogelijkheden voor batching en caching.
Een veelvoorkomende uitdaging bij REST is over- of under-fetching van data: te veel onnodige informatie krijgen, of niet genoeg van wat u in één keer nodig heeft. GraphQL voorkomt dit doordat u precies kunt opvragen wat nodig is — niet meer en niet minder. Deze precisie verbetert niet alleen de prestaties, maar vereenvoudigt ook het proces voor iedereen die met de API werkt, waardoor het systeem efficiënter en gebruiksvriendelijker wordt.
Voorbeelden van waar dit nuttig is:
Hiermee kunnen frontend-ontwikkelaars precies de data opvragen die ze nodig hebben voor hun UI-componenten, waardoor er minder round trips naar de server nodig zijn en de prestaties verbeteren.
Stel dat u een HS-codeclassificatie, cartonization, een shipment rating en een landed cost-quote wilt voor items in een checkout. Als u via de GraphQL API geïntegreerd bent, kunt u met de benodigde workflows één enkele call doen om alles te krijgen wat u nodig heeft (en niets wat u niet nodig heeft) in één antwoord. Met REST-API's zou u daarentegen eerst de Classify REST API moeten aanroepen, daarna afzonderlijk de Rating REST API, en die classificatie en shipment rating vervolgens moeten invoeren in uw derde aanroep naar de Landed Cost REST API. Al deze REST API's zouden alle informatie retourneren die ze kunnen, waardoor u de respons zou moeten doorzoeken op de data die u nodig heeft. Deze tijdsbesparing maakt het verschil bij het snel terugkrijgen van een volledige landed cost, voordat de shopper afhaakt.
GraphQL-API's hebben doorgaans één enkel eindpunt, in tegenstelling tot REST-API's, die vaak meerdere eindpunten hebben voor verschillende resources en acties. Dit maakt het eenvoudiger om de API te beheren en te begrijpen.
Het vermogen van GraphQL om queries te batchen en de ondersteuning voor caching-strategieën leiden tot aanzienlijke prestatieverbeteringen. Deze functies verminderen de belasting van netwerken en servers, wat resulteert in snellere en betrouwbaardere interacties voor gebruikers.
Goed gedefinieerde schema's
GraphQL-API's zijn gebaseerd op een sterk getypeerd schema. Dit schema definieert de structuur van de beschikbare data en de bewerkingen die kunnen worden uitgevoerd. Dit biedt duidelijkheid over welke data beschikbaar is en hoe u die kunt benaderen, wat de productiviteit van ontwikkelaars kan verhogen en fouten kan verminderen. Zo kunnen frontendteams bijvoorbeeld de graph verkennen om precies te krijgen wat ze nodig hebben, in plaats van te wachten op een nieuw REST-eindpunt.
Mogelijkheid om te verbeteren zonder bestaande clients te breken
Nieuwe functies toevoegen of bestaande aanpassen in GraphQL verstoort de huidige integraties niet, dankzij de flexibele querystructuur. Dit zorgt ervoor dat verbeteringen kunnen worden doorgevoerd zonder de compatibiliteit met bestaande clients te breken.
Actuele documentatie
Dankzij de introspectiefunctie van GraphQL wordt de documentatie automatisch gegenereerd en bijgewerkt bij elke wijziging. Dit zorgt ervoor dat alle informatie die aan ontwikkelaars wordt geboden actueel is, waardoor integratieproblemen en supporttickets over verouderde documentatie — een veelvoorkomende uitdaging bij REST API-documentatie — worden verminderd.
Stel u voor dat u in een restaurant bent met een menu waarmee u gerechten precies naar wens kunt samenstellen, tegenover een ander restaurant waar u alleen kunt kiezen uit vaste menu's. GraphQL is als het eerste restaurant:
Krijg precies wat u wilt: Met GraphQL kunt u exact de data opvragen die u nodig heeft, niet meer en niet minder. Stel dat u alleen de naam en prijs van een gerecht wilt, niet de volledige lijst met ingrediënten. Met REST-API's moet u alle gerechtdetails ophalen en de onderdelen die u niet nodig heeft, negeren.
Stel een gerecht op maat samen: Onze GraphQL-API kan eenvoudig worden gecombineerd om meer maatwerkoplossingen te creëren, vergelijkbaar met een buffetrestaurant waar u met de ingrediënten die al aanwezig zijn precies het unieke gerecht kunt samenstellen dat u nodig heeft. Een REST-API is daarentegen als een bakkerij met voorverpakte producten in mandjes — u kunt alleen bestellen wat al gemaakt is en niet kiezen om alleen het stuk mee te nemen dat u wilt.
Minder wachten: Omdat u alle benodigde informatie in één verzoek kunt ontvangen, is het alsof u uw ober vraagt om voorgerecht, hoofdgerecht en dessert allemaal tegelijk te brengen, in plaats van te wachten tussen de gangen. De meeste REST-API's vereisen dat u meerdere verzoeken verstuurt om verschillende stukjes informatie te krijgen.
Bestellingen eenvoudig aanpassen: Als de databehoeften van uw app veranderen, maakt GraphQL het eenvoudiger om dit aan te passen. U wijzigt gewoon de query voor wat u nodig heeft. Bij REST moet u misschien wachten tot de keuken (backend) een nieuw gerecht (eindpunt) voor het menu maakt, wat meer tijd kost.
GraphQL biedt meer flexibiliteit, efficiëntie en eenvoud bij het opvragen van data dan REST-API's, vooral wanneer uw behoeften veranderen of groeien.
Bij het moderniseren van ons platform de afgelopen jaren heeft Zonos ervoor gekozen om nieuwe functionaliteit voor onze API te bouwen met GraphQL in plaats van REST. Wij hebben hiervoor gekozen omdat onze data complex en onderling verbonden is, net als de data die Facebook ertoe bracht GraphQL te ontwikkelen. Deze complexiteit maakt het lastig om schaalbare REST-API's te bouwen, omdat de manieren waarop ontwikkelaars data moeten opvragen en gebruiken sterk verschillen per implementatie, en REST niet flexibel is.
GraphQL lost dit probleem elegant op door ontwikkelaars die onze API implementeren zelf te laten kiezen welke data ze willen en hoe ze die ontvangen. Zo kunnen zij het aanpassen aan hun eigen workflows, zonder dat Zonos voor elke situatie maatwerk moet leveren (terwijl zij daarop wachten).
Het gecombineerde resultaat van het gebruik van GraphQL en de moderniseringen van ons platform is dat onze API performanter is geworden, dat het integreren van Zonos in uw systemen sneller verloopt, en dat Zonos nieuwe functies sneller kan uitbrengen.
Betere functies
Zonos ontwikkelt continu nieuwe functies, en GraphQL is de eerste (en meestal de enige) die deze updates ontvangt. Onze REST-API's worden daarentegen als end-of-life beschouwd en hebben geen toegang tot veel van onze nieuwe functies.
Voorbeelden van functies die beperkt zijn tot GraphQL:
Inclusive pricing
Labels API
Nieuwe Checkout en Hello
Doosafmetingen in het API-antwoord
Dashboard-rapportage
Mogelijkheid om een DDP-quote aan te vragen indien beschikbaar, maar toch een DDU-quote te retourneren als DDP niet beschikbaar is voor dat land met dat serviceniveau
Gedetailleerde uitsplitsing van invoerrechten, belastingen en kosten (informatie op itemniveau, specifieke kosten) — Dashboard wordt aangedreven door GraphQL en toont deze data voor alle winkels, maar de REST API-respons biedt dit detailniveau niet
Waarom GraphQL
Waarom GraphQL
Ontdek waarom wij aanraden om te integreren via GraphQL in plaats van REST.
Bij Zonos bieden wij twee hoofdtypen API's voor integratie: GraphQL en REST. REST-API's bestaan al langer en zijn voor velen wellicht bekender, maar wij zijn overgestapt op GraphQL om meer flexibiliteit en snellere innovatie mogelijk te maken. Beide worden nog steeds ondersteund, maar deze gids legt uit waarom GraphQL niet alleen de toekomst van onze integraties is, maar ook de toekomst van integraties in het algemeen, en een krachtiger middel om vandaag aan uw behoeften te voldoen.
Wat is GraphQL?
GraphQL is een alternatieve manier om met API's te communiceren, die zich uitstekend leent voor complexe datastructuren en het bouwen van interfaces daarop. In plaats van data als losse, op zichzelf staande onderdelen te behandelen, laat GraphQL zien hoe databrokken met elkaar samenhangen, waardoor het eenvoudig wordt om informatie op te vragen en te ontvangen.
Zie GraphQL als een querytaal waarmee u met de API communiceert alsof u rechtstreeks met de database praat. Met GraphQL komt u zo dicht mogelijk bij de database, zodat u zelf kunt kiezen welke data u wilt en hoe u die ontvangt, wat een enorm prestatievoordeel oplevert.
GraphQL is ontwikkeld door Facebook om het probleem van schaalbaarheid bij complexe datastructuren op te lossen. Dankzij het succesvolle gebruik ervan zien steeds meer bedrijven de voordelen van GraphQL voor hun API's in.
Kent u REST al? GraphQL zal u bekend voorkomen.
GraphQL-API's zijn eenvoudiger te gebruiken dan u misschien denkt. Als u gewend bent om met REST-API's te werken, ziet u hier hoe de kernconcepten van REST zich vertalen naar GraphQL.
Voordelen van GraphQL
Snellere responses
GraphQL levert snellere responses dankzij precieze data-opvraging, het gebruik van één enkel eindpunt en verbeterde mogelijkheden voor batching en caching.
Precieze data-opvraging
Een veelvoorkomende uitdaging bij REST is over- of under-fetching van data: te veel onnodige informatie krijgen, of niet genoeg van wat u in één keer nodig heeft. GraphQL voorkomt dit doordat u precies kunt opvragen wat nodig is — niet meer en niet minder. Deze precisie verbetert niet alleen de prestaties, maar vereenvoudigt ook het proces voor iedereen die met de API werkt, waardoor het systeem efficiënter en gebruiksvriendelijker wordt.
Voorbeelden van waar dit nuttig is:
Één enkel eindpunt
GraphQL-API's hebben doorgaans één enkel eindpunt, in tegenstelling tot REST-API's, die vaak meerdere eindpunten hebben voor verschillende resources en acties. Dit maakt het eenvoudiger om de API te beheren en te begrijpen.
Batching en caching
Het vermogen van GraphQL om queries te batchen en de ondersteuning voor caching-strategieën leiden tot aanzienlijke prestatieverbeteringen. Deze functies verminderen de belasting van netwerken en servers, wat resulteert in snellere en betrouwbaardere interacties voor gebruikers.
Goed gedefinieerde schema's
GraphQL-API's zijn gebaseerd op een sterk getypeerd schema. Dit schema definieert de structuur van de beschikbare data en de bewerkingen die kunnen worden uitgevoerd. Dit biedt duidelijkheid over welke data beschikbaar is en hoe u die kunt benaderen, wat de productiviteit van ontwikkelaars kan verhogen en fouten kan verminderen. Zo kunnen frontendteams bijvoorbeeld de graph verkennen om precies te krijgen wat ze nodig hebben, in plaats van te wachten op een nieuw REST-eindpunt.
Mogelijkheid om te verbeteren zonder bestaande clients te breken
Nieuwe functies toevoegen of bestaande aanpassen in GraphQL verstoort de huidige integraties niet, dankzij de flexibele querystructuur. Dit zorgt ervoor dat verbeteringen kunnen worden doorgevoerd zonder de compatibiliteit met bestaande clients te breken.
Actuele documentatie
Dankzij de introspectiefunctie van GraphQL wordt de documentatie automatisch gegenereerd en bijgewerkt bij elke wijziging. Dit zorgt ervoor dat alle informatie die aan ontwikkelaars wordt geboden actueel is, waardoor integratieproblemen en supporttickets over verouderde documentatie — een veelvoorkomende uitdaging bij REST API-documentatie — worden verminderd.
Bekijk onze GraphQL-documentatie en onze REST-documentatie om het verschil te zien.
Een analogie
Stel u voor dat u in een restaurant bent met een menu waarmee u gerechten precies naar wens kunt samenstellen, tegenover een ander restaurant waar u alleen kunt kiezen uit vaste menu's. GraphQL is als het eerste restaurant:
GraphQL biedt meer flexibiliteit, efficiëntie en eenvoud bij het opvragen van data dan REST-API's, vooral wanneer uw behoeften veranderen of groeien.
Hoe Zonos GraphQL gebruikt
Bij het moderniseren van ons platform de afgelopen jaren heeft Zonos ervoor gekozen om nieuwe functionaliteit voor onze API te bouwen met GraphQL in plaats van REST. Wij hebben hiervoor gekozen omdat onze data complex en onderling verbonden is, net als de data die Facebook ertoe bracht GraphQL te ontwikkelen. Deze complexiteit maakt het lastig om schaalbare REST-API's te bouwen, omdat de manieren waarop ontwikkelaars data moeten opvragen en gebruiken sterk verschillen per implementatie, en REST niet flexibel is.
GraphQL lost dit probleem elegant op door ontwikkelaars die onze API implementeren zelf te laten kiezen welke data ze willen en hoe ze die ontvangen. Zo kunnen zij het aanpassen aan hun eigen workflows, zonder dat Zonos voor elke situatie maatwerk moet leveren (terwijl zij daarop wachten).
Het gecombineerde resultaat van het gebruik van GraphQL en de moderniseringen van ons platform is dat onze API performanter is geworden, dat het integreren van Zonos in uw systemen sneller verloopt, en dat Zonos nieuwe functies sneller kan uitbrengen.
Betere functies
Zonos ontwikkelt continu nieuwe functies, en GraphQL is de eerste (en meestal de enige) die deze updates ontvangt. Onze REST-API's worden daarentegen als end-of-life beschouwd en hebben geen toegang tot veel van onze nieuwe functies.
Voorbeelden van functies die beperkt zijn tot GraphQL:
Was deze pagina nuttig?