5.8 Direct Comparison

Now that we understand REST GraphQL in more detail, let us compare why the two architectures and articulate why we believe GraphQL is better than REST for a majority today’s use cases, and why it will become entirely dominant in years to come.

Let us model a company's API as a vending machine. With traditional REST, a client presses one button on the vending machine and gets one thing. So, the client has to press lots of buttons one at a time to get everything the developer needs. This process is slow. One way to solve this problem is to create special purpose buttons, which let the client get multiple things at once. Another way is to allow the client to press a special purpose button and get a lot of information at once from the vending machine, but the client can’t perfectly control the information it receives, which can lead to you transferring more information than is needed in some cases, increasing bandwidth and latency. GraphQL solves the aforementioned inefficacies in the vending machine: vending machine that allows for the client to press exactly one smart button that gives the client everything the client wants in one go.

GraphQL solves these issues by having a single ‘smart’ endpoint rather than having many ‘dumb’ endpoints. The key benefit is that smart endpoints are able to take complex queries and shape the data output into whatever the client requires. Essentially, the GraphQL layer exists between the client and data sources. Its job is to receive client requests and fetch the necessary data based on the client’s requirements. The GraphQL approach to querying addresses a wide range of large-scale app development problems.

As you can imagine, GraphQL addresses most of the main weaknesses of REST that were mentioned previously:

• Multiple Round Trip (Latency): Now that the client can push complex queries to the server, and have it return all of the client’s desired information in one go, round-trips are an item of the past.

• Verbose: With GraphQL the client only gets back the information the client requested, no more irrelevant information.

• Security with Multiple Endpoints: With GraphQL, the server only has one endpoint to protect, rendering a significantly easier task for back-end security efforts.

• Documentation: Given that GraphQL is strongly typed, it’s a lot easier to automate the creation of documentation; there are a number of services that will do this for back-end developers. There are also great dashboards that back-end developers can use to experiment with different queries and see how the queries will be responded to by the back-end server.

• Updates: Additional fields can easily be added to the server, i.e. adding new product features or deprecating older features, without affecting existing clients. In this way, GraphQL brings about a backward-compatible process that eliminates the need for incrementing version numbers, simplifying versioning in general.

This is in fact one of the most valuable aspects of GraphQL - it doesn’t lose any of the functionality that made REST so great, whilst improving on a lot of its weaknesses. It is a rare example of a net additive to a widely adopted system, why it has gained popularity so quickly.

It is also fairly easy to convert from an existing REST API to a GraphQL API, and given the low switching cost and explosion of managed tools to help maintain a GraphQL system, the choice to migrate is only going to get easier.

All this being said, GraphQL is far from a perfect system. In fact, similarly to Kubernetes [37], the reason it provides so many distinct benefits is because it is a significantly more complex system than REST.