REST vs. GraphQL: Making the right choice

In order to better understand the “REST vs. GraphQL” debate, it’s useful to look at where GraphQL comes from. It started with Facebook’s observation that their HTTP-based API powering the UIs was too chatty and did not allow more specific requests (to avoid over-fetching). This made Facebook go back to the drawing board and change their internal API.

One option to overhaul their internal API (which connects Facebook apps such as on the phone and in the browser to their back-end) would have been to change the design of the REST API and to create more coarse-grained resources and add filtering capabilities.

However, Facebook decided to go with an entirely different API style, and they created the query-style GraphQL language as an alternative. It is interesting to consider that even today, Facebook uses GraphQL only for their internal API (to connect their own front-ends with their own back-end) whereas the public Facebook APIs are still resource-oriented REST APIs.

There are various situations today where REST (meaning: resource-oriented HTTP-based APIs) and GraphQL are seen as design alternatives. This begs the question: What is the right choice? As in all design (“Design depends largely on constraints,” after all…), this question does not have one right answer. But it’s interesting to think whether certain considerations are especially relevant to choosing between the two alternatives. The following four considerations provide a useful starting point for making that decision:

1.​ API landscape: Often your API does not exist in isolation, but it is part of an API landscape. It makes sense to think about how well it fits into that landscape and how the landscape may evolve.

2. Data or workflows: Some APIs are more data-centric and primarily provide access to data; for these GraphQL can be an appropriate choice. Other APIs are more workflow-centric and allow users to have process-oriented conversations with the API; for these REST often is the better option.

3.​ Listen to consumers: APIs are designed and provided for consumers, so it is important to think about who the API is designed for. GraphQL was used as an API between UIs and APIs in data-centric settings, and it can be a good choice for that scenario.

4.​ Design APIs properly: Don’t let your choice be dictated by tools or easy ways to create the API. The primary concern always should be to design an API that provides a good way to interact with a capability and to make sure that it is designed with its users in mind.

If you’re interested in more details around these considerations, feel free to check out the following video which goes into more detail about everything discussed here.