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.
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
Adding new features or modifying existing ones in GraphQL does not disrupt current integrations, thanks to its flexible query structure. This capability ensures that improvements can be made without breaking compatibility with 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 APIs 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)
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.