sommai - Fotolia


GraphQL vs. REST: Nailing down the pros and cons of each

While no one can deny the popularity of REST, GraphQL has emerged as a viable contender to REST, particularly when it comes to certain data structures. Zach Flower explains.

For years, representational state transfer has been one of the most popular API architectural styles on the web,...

favored by companies like Twitter and Google. However, because of some drawbacks with REST, some developers have turned to GraphQL as an alternative. So, how do you determine a winner in the GraphQL vs. REST debate?

A crash course in REST

The central idea behind REST API design is the resource. A typical REST API will comprise a distinct endpoint for each resource, with different HTTP request methods defining how that resource will be interacted with.

For example, let's say that you have a basic blog API with two resources: articles and authors. The core endpoint for each resource might follow the following pattern:

METHOD /api/:resource:/:id:

What this means is: In order to look up a list of every article using the provided API, you would have to make a GET request to the root resource endpoint, as is shown here:

GET /api/articles

If you wanted to then query for an individual article, you would append the resource ID to the endpoint as well:

GET /api/articles/1

While this means that REST APIs can become very verbose, standard create, read, update and delete (CRUD) actions can be intuitively composed for each resource. In typical REST parlance, to update an individual resource, you would use the PATCH request method instead of GET. Creating a resource uses POST, and DELETE removes a resource.

Ease of use and an intuitive structure have largely contributed to the popularity of REST as an API design methodology. But just because it is popular doesn't mean it is always the right choice. Not every application justifies the use of a CRUD structure, and operations like searching, dealing with large data sets and working with binary files can all break the clean and organized feel of any REST API.

Comparing REST and GraphQL

GraphQL as an alternative

Because of these drawbacks, one architectural style that is becoming a favorite among API developers is GraphQL. In contrast to REST's highly structured, resource-driven design, GraphQL acts as a more flexible query language on top of an API. This allows consumers to interact with an API in a very programmatic way, rather than the more rigid REST API black box.

If you revisit the blog API example from above in the context of GraphQL, then every request you make can be performed on one endpoint, with the actions being taken and data being returned defined within the query itself, as shown below:

GET /api?query={ article(id:"1") { title, content } }

This query instructs the API to look up an article with the ID of 1 and then return its title and content. This same endpoint can also be used to perform actions within the API as well. These are called mutations, and they are predefined methods that can be called by the client:

POST /api?mutation={ updateArticle(id: "1", title: "new title") { title, content } }

So, given the higher flexibility of GraphQL versus the intuitive nature of REST, when is one a better choice over the other?

GraphQL vs. REST: The GraphQL argument

At a high level, GraphQL is an excellent design choice when your application's data structure requires a large number of queries within a REST API. Given the blog API example, if you wanted to query for an article and then get that article's author, tags and comments, then, at minimum, that would require four separate queries. With GraphQL, requesting this data can be done in a much more programmatic way, allowing the client to query for the exact information they need.

GraphQL is also a great way to reduce version-breaking changes that can happen when resources and data schemas change in a REST API. When clients query for the exact information they need, any additional data points or relationships won't interfere with existing implementations. As your data set grows and you optimize your database schema in ways that don't follow traditional resource-driven REST design, GraphQL will abstract this complexity and allow clients to interact with the changing data set in a consistent and predictable way.

GraphQL vs. REST: The REST argument

On the flip side, the biggest advantage to a REST API over GraphQL is the ease in which data can be cached and the transparency of the actions performed on the API itself. Back to the blog API example, when a client wants to query for article x, that request and data will be consistent for every client. The data being returned can be cached on the server side for subsequent API requests, which can reduce database load and speed up the API response time.

REST is also a perfect choice for highly structured data sets and applications, where the actions being performed on the API follow a predictable pattern. Creating, reading, updating and deleting distinct resources within the API are all actions that make sense in a REST context.

Further considerations in GraphQL vs. REST

REST and GraphQL both have their own distinct advantages. But one of the most important factors to consider beyond scalability and technology is the consumer. As with all things, understanding your market can play a big factor in your success. A standard CRUD application will be best served by a REST API, but if you are building an internal tool for teams that only have experience with GraphQL APIs, then GraphQL might be a better choice to reduce friction and maintain productivity. The same can be said for developing a GraphQL API for end users using programming languages that are better served by a REST API. Thankfully, when it comes to software development, there are no best solutions, only well-considered ones.

Next Steps

Learn how to make the choice between REST and SOAP

Discover how REST changed the world of service-oriented architecture

See if you can answer these five questions about RESTful design

Dig Deeper on Development platforms