REST (Representational State Transfer) and GraphQL are two common architectural styles used for developing web APIs. Choosing between REST and GraphQL depends on the specific needs and goals of an API. This article provides an overview of REST and GraphQL, compares their strengths and weaknesses, and offers guidance on when each architectural style is most appropriate.
What is REST?
REST is an architectural style for building distributed systems based on hypermedia. It relies on a stateless client-server protocol, most commonly HTTP. With REST, servers provide resources (data objects) that clients can manipulate through the standard HTTP methods – GET, POST, PUT, PATCH, and DELETE.
REST uses URL endpoints to expose resources and actions. URLs should be based on nouns (the resource) and not verbs (the operations on the resource). For example, a RESTful URL for a list of users might look like:
https://api.example.com/users
REST responses typically return JSON or XML data. RESTful systems aim to expose data as resources that can be easily understood and manipulated. A defining feature of REST is statelessness, meaning no client context is stored on the server between requests. Each request contains all the information needed to complete itself.
What is GraphQL?
GraphQL is a query language created by Facebook to build client applications based on intuitive queries. It provides an alternative to REST for fetching data from servers. With GraphQL, clients can specify exactly what data they need in a query. The GraphQL server responds with that data in a predictable way.
GraphQL only exposes a single endpoint that accepts these queries. The shape of responses is determined by the client rather than the server. For example, a GraphQL query might look like:
“`
query {
user(id: “123”) {
name
email
}
}
“`
This query asks for the name and email properties of a user with ID 123. The response will contain exactly that data in JSON format. GraphQL is strongly typed, allowing APIs to be fast and efficient.
Key Differences
Here are some key differences between REST and GraphQL:
| REST | GraphQL |
|---|---|
| Uses predefined endpoints and standard HTTP methods to expose resources | Exposes a single endpoint and uses a JSON-based query language to specify data needs |
| REST responses can contain a lot of extra data not needed by the client | GraphQL responses contain exactly the data requested by the client |
| REST endpoints map closely to database models | GraphQL is organized around business objects and UI needs, not database models |
| REST is less efficient for complex queries requiring multiple database lookups | GraphQL can fetch related data in a single request to avoid multiple round trips |
| REST uses multiple URLs and verbs (GET, POST, etc) to make changes | GraphQL uses a single URL and verb (POST) to read and write data |
When to Use REST
Here are some good use cases for a RESTful API architecture:
- You want to expose resources for public consumption. REST has become the standard for public web APIs.
- You want to take advantage of widely-adopted tooling, community support, and documentation around REST.
- Your API needs to support a very wide range of clients written in different languages and running on different platforms. REST is the lowest common denominator API.
- You don’t need the complex query flexibility of GraphQL. Simple CRUD operations satisfy your use cases.
- Your data fits neatly into separate resources that can be manipulated through CRUD. GraphQL may be overkill.
Use REST When
- You want a simple, lightweight interface to your API
- You want to expose resources through standards like HTTP that are widely understood
- You are building public APIs consumed by a wide range of unknown clients
- The structure of your data fits cleanly into individual resources
- You don’t need to manipulate lots of different resources in a single request
When to Use GraphQL
Here are some situations where GraphQL may be a good choice over REST:
- Your app needs to query lots of different resources in a single request. GraphQL can fetch all related data in one round trip.
- Your app needs predictable queries and mutations. With GraphQL, you always know what data you’ll get back.
- Your API consumers need rapid feature development. GraphQL enables quick iteration on products.
- You want to decouple your API from your database schema. GraphQL abstracts storage implementations.
- You want to build client apps that require less network traffic and bandwidth usage. GraphQL only requests what you need.
Use GraphQL When
- Your app needs to query multiple, related pieces of data in one request
- Your client requirements are constantly changing and you need to iterate quickly
- You want your API interface to be driven by client requirements, not storage models
- Your clients consume substantial bandwidth fetching unneeded data
- You want clients to be able to query your API using intuitive syntax
Conclusion
REST and GraphQL both enable developers to build robust client applications that can consume and manipulate data from servers. REST provides a simple, standard interface based on HTTP requests to predefined endpoints manipulating resources. GraphQL enables flexible queries against a single endpoint, returning only requested data. The strengths and weaknesses of each style lend themselves to different use cases.
For public APIs consumed by a wide range of unknown clients, REST is a good choice thanks to widespread familiarity with RESTful standards. For internal or consumer-facing APIs that need flexible queries, real-time updates, or rapid iteration, GraphQL is likely the better choice. Evaluating the specific needs of API consumers and the structure of the underlying data will determine when REST or GraphQL is more appropriate.
By understanding the key differences in how REST and GraphQL APIs are designed and used, developers can make an informed decision between the two architectures. Both REST and GraphQL are mature technologies with active open source communities. The popularity of GraphQL is growing quickly, but REST remains dominant for public APIs. As needs evolve, developers now have the flexibility to choose either REST or GraphQL depending on which style best fits their use cases.