GraphQL is a query language for APIs that was developed by Facebook in 2012 and open sourced in 2015. It provides an alternative to REST APIs and has been gaining popularity over the past few years, especially among technology companies building mobile and web applications.
What is GraphQL?
GraphQL is often described as a syntax that allows clients to define the structure of the data required from the API. It is an application layer query language that uses a type system to define the data. GraphQL APIs provide predictable results and give more control to the client to ask for precisely the data they need.
Some key features of GraphQL include:
- Hierarchical – The structure of a GraphQL query mirrors the structure of the output data.
- Product-centric – The query is tailored to the data requirements of the client rather than the server.
- Strongly-typed – There is a strict validation process for requests.
- Introspective – GraphQL APIs can be queried for metadata.
- Developer friendly – GraphQL APIs provide better developer workflows and more efficient ways to retrieve data.
Overall, GraphQL enables declarative data fetching where the client can specify exactly what data it needs from the API. This contrasts with REST APIs where the server determines what data to send back to the client.
When should you use GraphQL?
Here are some of the main scenarios where using GraphQL makes sense:
You need to query multiple endpoints
REST APIs often require multiple roundtrips between the client and server to gather the required data. For example, you may need to first fetch data about a product, then fetch reviews for that product, then fetch related products. With GraphQL, you can get all this data in a single request since clients can specify exactly the data they need in one query.
You need to query against multiple data sources
GraphQL APIs are capable of querying multiple databases, microservices, and other data sources in one go. The GraphQL server acts as an aggregation layer that handles the complexity behind the scenes. This simplifies things for the client.
You want to decouple frontends and backends
With REST, backend and frontend are often highly coupled since the endpoints exposed by the backend need to be specifically consumed by the frontend. With GraphQL’s product-centric and hierarchical approach, frontend developers can consume data based on their UI needs rather than backend constraints. This results in better separation of concerns.
You need faster feature development
GraphQL’s flexible querying model enables frontend developers to get the exact data requirements fulfilled without having to wait for backend engineers to expose new endpoints. This allows for faster iterations.
Your data has complex relationships
Fetching relational data with nested relationships via REST endpoints can get complex. GraphQL’s hierarchical structure and ability to traverse relationships easily is well-suited for consuming denormalized or relational data.
You need API evolution over time
Because GraphQL queries are loosely coupled to the backend, APIs can evolve over time without impacting existing queries. Adding new fields and types only impacts clients that want to query that new data. Old queries keep working as is.
When should you avoid GraphQL?
While GraphQL makes sense in many cases, there are a few scenarios where it may not be the best architectural choice:
You need simple CRUD operations
For basic create, read, update, and delete operations, GraphQL may be overkill. A simple REST or RPC-based API may work fine.
You want low overhead
GraphQL requires more effort to implement caching, documentation, error handling, etc. compared to simple REST APIs. If you want to get an API up quickly, REST may involve less overhead.
You need scalability
For large-scale public APIs that need to handle enormous traffic and load, GraphQL may not be the best choice today. REST is likely better optimized for CDNs and edge caching currently.
You want API discoverability
GraphQL only exposes a single endpoint and requires that developers understand the schema to query effectively. REST provides more discoverability since endpoints usually represent resources.
Your API needs to be very stable
GraphQL’s flexibility makes it great for evolving APIs. But if your API needs to be very strictly versioned, REST may work better.
Should you use GraphQL or REST?
GraphQL and REST are often portrayed as rivals, but in reality they solve different problems and can also complement each other. Here are some things to consider:
| GraphQL | REST |
|---|---|
| More efficient for apps needing less data transfer | More suitable for public APIs requiring caching, discoverability |
| Breaks away from resource-based endpoints | Organized around resources and URLs |
| Focused on client requirements | Focused on server constraints / capabilities |
| Evolves based on client needs | Evolves by adding endpoints |
| Single endpoint | Multiple endpoints |
So in summary:
- GraphQL is great for frontend-driven mobile and web apps querying internal APIs.
- REST makes sense for public APIs consumed by a diverse set of clients.
- For internal microservices, either REST or GraphQL could make sense depending on needs.
Many projects use a mix of REST and GraphQL. For example, you could have a public REST API that is consumed by internal GraphQL servers to combine data before serving it to clients. Or REST could be used for simplistic CRUD while GraphQL handles complex queries.
Conclusion
GraphQL provides an elegant and flexible approach to fetching data for modern applications. While REST continues to be a solid choice for public APIs, GraphQL is emerging as the architecture of choice for internal APIs used by mobile and web clients. It addresses many of the shortcomings of REST and suits today’s more client-driven development workflows.
That said, GraphQL does have a learning curve and brings its own challenges. REST is still going to be a better fit for some use cases. As with any new technology, you need to fully understand the pros and cons before adopting. But for many usage scenarios, GraphQL does provide tangible benefits over REST in terms of efficiency, flexibility and developer experience.