Developers love the REST API protocol for its simplicity, caching, and scalability. It’s a great choice for many types of applications, but for others, GraphQL has become an increasingly popular option. In fact, Intuit has been working with GraphQL since 2017. Although we’re still relatively early in our adoption, we already use GraphQL to process as many as two billion requests per day.
While GraphQL offers high flexibility and efficiency, and Intuit has successfully processed billions of requests with it, it’s important to acknowledge that GraphQL isn’t a one-size-fits-all solution. It can pose challenges for adoption, migration, and scalability, and may not be ideal for every scenario. Sometimes REST is still the best way to go, and the appropriate choice depends heavily on the specific use case.
In this blog, we’ll explore the pros and cons of each protocol to help you make the right decision for each of your applications.
REST: Familiar, reliable—and a little inflexible
Everyone knows REST. There are ample libraries available for both producing and consuming APIs, as well as tools to simplify testing and implementation on both sides. Requests return a predictable amount of data in terms of attributes and payload size, making it easy to plan and scale your infrastructure. Changing only infrequently, REST APIs offer stability and reliability for both servers and consumers.
On the other hand, some of these strengths also translate into drawbacks:
- Over-fetching: Returning every field, every time—even if you only needed a few—makes for considerable inefficiency. Imagine you’re building a mobile app that only needs a user’s name and profile picture. A REST API might return a large user object with address, phone number, order history, and other data that your app doesn’t need. This wastes bandwidth and processing power on the client side.
- Under-fetching: If your data resides in multiple places, you’ll have to reach out to each endpoint separately to get everything you need and then stitch it all together. Let’s say you’re displaying a product on a page. You need the product details from one endpoint, the seller information from another, and customer reviews from yet another. With REST, you’d have to make three separate requests and then combine the data yourself, leading to multiple round trips and potential delays.
- Dependency on API producer: If a needed attribute isn’t included in the endpoint, you’ll have to make a feature request to your API dev team and then figure out how this new data connects to other API responses or endpoints.
All of which is to say: REST isn’t the most flexible protocol in the world.
GraphQL: One endpoint, just-right data
With a REST API, clients have to access a different endpoint for each type of data. Backend developers sometimes use a backend-for-frontend (BFF) pattern to get around this issue, creating a tailored backend that aggregates the data into a single interface for the frontend, but this approach can bog down as soon as additional attributes are needed.
GraphQL avoids this built-in inefficiency by providing a single endpoint to retrieve data from all of your services. It also allows flexible queries for specific attributes.
Essentially, a GraphQL query is a request for specific data fields. You tell the API exactly what data you need, and it returns only those fields. This is achieved using a declarative query language where you define the structure of the data you want in the response. The API then resolves this query and provides the requested data in a JSON-like format. This puts the consumer in charge, able to get exactly the right data for each use case without over-fetching or under-fetching, and without depending on the API development team.
The backend services that provide this functionality can be written in any language. GraphQL APIs are built around a schema, which is a blueprint of the data that’s available. The schema defines the types of objects and their fields, as well as the relationships between them. When a client makes a query, the GraphQL server validates it against the schema to ensure the request is for valid data.
These advantages do involve a few tradeoffs, however. GraphQL is a newer technology and there’s a learning curve for both producers and consumers. Migrating current consumers to GraphQL isn’t exactly simple (though we’ll outline the steps and best practices in a future article). When consumers can grab as much or as little data as they want, you may see unexpected spikes in traffic. The ability to combine multiple data types in a single query can mean that authorization happens at different levels, like specific fields or nested data, rather than just at fixed endpoints. Keeping security consistent and manageable takes careful planning.
Making the choice
So: which one should you use? There’s no simple answer; it depends on your use case. As you make your decision between REST and GraphQL, consider these aspects of your project:
Existing infrastructure
- REST: If you have an established REST API ecosystem with well-defined endpoints and tooling, it might be simpler to stick with REST, especially for straightforward data retrieval.
- GraphQL: If you’re integrating many disparate data sources or building a new API layer on top of existing services, GraphQL can provide a unified interface and reduce the need for multiple API calls.
New development vs. migration
- REST: For simple, CRUD-based applications with predictable data needs, REST can be quicker to set up for new projects.
- GraphQL: For complex applications with evolving data requirements, or if you anticipate frequent changes to data structures, GraphQL’s flexibility can be a significant advantage in new projects. For migration, consider a phased approach, introducing GraphQL gradually, as we will describe in a future article.
Team skills and experience
- REST: Most developers are familiar with REST, making it easier to onboard team members and start development quickly.
- GraphQL: GraphQL requires a learning curve, so ensure your team has or is willing to acquire the necessary skills. However, the long-term benefits of its flexibility and efficiency can outweigh the initial training.
Business needs and use cases
- REST: REST is suitable for simple data retrieval, public APIs with limited complexity, and scenarios where caching is crucial.
- GraphQL: You’ll be better off with GraphQL for complex UIs with dynamic data needs (e.g., dashboards and mobile apps), internal APIs where flexibility is paramount, and situations where minimizing data transfer is critical. Intuit has found GraphQL especially useful for north-south traffic (client to gateway) where many different clients need to retrieve data.
Intuit’s own GraphQL journey may offer valuable insights for your decision process. In our article Intuit Tech Stories: the GraphQL journey we discuss how and where we opted for GraphQL for our own applications, and share a few tips on tools, migration, and best practices.
Contributing authors include Jared Cheney and Lucy Shen.