Why GraphQL

Discover why we recommend integrating via GraphQL over REST.

At Zonos, we offer two main types of APIs for integration: GraphQL and REST. While REST APIs have been around longer and may be more familiar to many, we have moved to GraphQL to allow more flexibility and faster innovation. While both are still supported, this guide explains why GraphQL is not only the future of our integrations but also the future of integrations in general and a more powerful tool to meet your needs today.

What is GraphQL?

GraphQL is an alternative way of talking to APIs that is highly suited for complex data structures and building interfaces on top of them. Unlike treating data as separate, standalone pieces, GraphQL shows how data pieces connect and relate to each other, making it easy to ask for and receive information.

Think of GraphQL as a query language that allows you to talk to the API as if you were talking directly to the database. Using GraphQL allows you to get as close to the database as possible, letting you pick and choose what data you want and how you get it, providing a massive performance benefit.

GraphQL was created by Facebook to solve the problem of scaling with complex data structures. As a result of their successful adoption of it, more and more companies have started to realize the benefits of using GraphQL for their APIs.

Already know REST? GraphQL will feel familiar.

GraphQL APIs are easier to work with than you may think. If you are used to working with REST APIs, here’s how core concepts from REST translate into GraphQL.

Feature↕	REST↕	GraphQL↕
Endpoint	Requests are made to multiple endpoints for different actions	All requests are made to a single endpoint (e.g., /graphql)
Data retrieval	Use GET methods on specific endpoints to retrieve data	Use queries to request exactly the data needed, reducing over-fetching or under-fetching
Data modification/actions	Use HTTP methods like POST, PUT, PATCH, or DELETE to modify or process data.	Use mutations to perform operations (e.g., create parties, calculate landed costs)
Response format	Fixed response formats return all predefined fields, regardless of whether they’re needed	Flexible responses allow specifying exactly the fields to include, reducing unnecessary data transfer (If this flexibility feels complicated, simply use the pre-written query examples in our documentation for a RESTful experience)
Data connection	Multiple requests are often required to fetch related data	Nested queries enable retrieving related data in a single request (e.g., party details and shipment items together). Users can also build workflows to manage multiple mutations within a single GraphQL request, reducing complexity and improving efficiency

Advantages of GraphQL

Faster responses

GraphQL provides faster responses through precise data retrieval, use of a single endpoint, and improved capabilities for batching and caching.

Precise data retrieval

A common challenge with REST is over-fetching or under-fetching data—either getting too much unnecessary information or not enough of what's needed in one go. GraphQL eliminates this by allowing requests for exactly what's needed—nothing more, nothing less. This specificity not only improves performance but also simplifies the process for those interacting with the API, making the system more efficient and user-friendly.

Examples of how this is useful:

This allows frontend developers to fetch exactly the data they need for their UI components, reducing the number of round trips to the server and improving performance.
Imagine you want to get an HS code classification, cartonization, shipment rating, and landed cost quote on items in a checkout. If you are integrated via GraphQL API, you can make a single call with the necessary workflows to get everything you need (and nothing you don't need) in a single response. By contrast, with REST APIs, you would need to first call the Classify REST API, then call the Rating REST API separately afterward, and finally plug that classification and shipment rating into your third call to the Landed Cost REST API. All of these REST APIs would return every piece of information that they can, causing you to have to parse through the response for the data you need. This savings in speed makes an impact in returning a complete landed cost quickly, before the shopper leaves.

Single endpoint

GraphQL APIs typically have a single endpoint, unlike REST APIs which often have multiple endpoints for different resources and actions. This makes it simpler to manage and understand the API.

Batching and caching

GraphQL's ability to batch queries and its support for caching strategies lead to significant performance improvements. These features reduce the load on networks and servers, translating to faster, more reliable interactions for users.

Well-defined schemas

GraphQL APIs are based on a strongly typed schema. This schema defines the structure of the data available and the operations that can be performed. This provides clarity on what data is available and how to access it, which can improve developer productivity and reduce errors. For example, frontend teams can explore the graph to get exactly what they need instead of waiting for a new REST endpoint.

Ability to improve without breaking existing clients

Up-to-date documentation

Thanks to GraphQL's introspection feature, documentation is automatically generated and updated with every change. This ensures that all information provided to developers is current, reducing integration issues and support tickets related to outdated documentation—a challenge commonly faced with REST API documentation.

Review our GraphQL documentation and our REST documentation to see the difference.

An analogy

Imagine you're at a restaurant with a menu that lets you order dishes exactly as you like them, compared to another restaurant where you can only choose from set meals. GraphQL is like the first restaurant:

Get exactly what you want: With GraphQL, you can ask for exactly the data you need, no more, no less. Imagine you only want the name and price of a dish, not the whole list of ingredients. With REST APIs, you have to get the entire dish details and ignore the parts you don't need.
Compose a custom dish: Our GraphQL API can be easily combined to create more custom solutions, simliar to a buffet-style restaurant where you can create a one-of-a-kind dish exactly as you need it, using ingredients they already have. By contrast, a REST API is like a bakery with pre-made goods packaged in baskets—you can only order what has already been created and you cannot choose to take home only the piece you want.
Less waiting: Since you can get all the information you need in a single request, it's like asking your server to bring your appetizer, main course, and dessert all at once, rather than waiting between courses. Most REST APIs require you to send multiple requests to get different pieces of information.
Easy to change orders: If your app's data needs change, GraphQL makes it easier to adjust. You just change the query for what you need. With REST, you might need to wait for the kitchen (backend) to create a new meal (endpoint) for the menu, which takes more time.

GraphQL offers more flexibility, efficiency, and simplicity for fetching data than REST APIs, especially as your needs change or grow.

How Zonos uses GraphQL

While modernizing our platform over the past couple of years, Zonos has made the choice to build new functionality using GraphQL for our API instead of REST. We decided to do this because our data is complex and interconnected, much like the data that led Facebook to create GraphQL. This complexity makes it challenging to build scalable REST APIs because the ways that developers need to fetch and use the data varies dramatically between implementations, and REST is not flexible.

GraphQL neatly solves this problem by allowing developers implementing our API to pick and choose exactly what data they want and how they get it. This allows them to fit it into their workflows without Zonos needing to do custom work (while they wait) for every situation.

The combined result of using GraphQL and the modernizations in our platform have made our API more performant, made integrating Zonos into your systems faster, and made it possible for Zonos to deliver new features more quickly.

Better features

Zonos continuously develops new features, and GraphQL is the first (and usually only) one to receive these updates. By contrast, our REST APIs are considered end-of-life and cannot access many of our new features.

Examples of features limited to GraphQL:

Inclusive pricing
Labels API
New Checkout and Hello
Box sizes in API response
Dashboard reporting
Ability to request a DDP quote if possible, but still return a DDU quote if DDP is unavailable to that country with that service level
Detailed breakdown of duties, taxes, and fees (item-level information, specific fees)—Dashboard is powered by GraphQL and shows this data for all stores, but the REST API response does not include this level of detail
Test mode (coming soon)

Book a demo