"GraphQL vs REST" is ill-typed
Tags: graphql, rest, pedantry
Published: 2019-10-25 23:26:26

## What?

"Wait just a minute.. What do you mean 'ill-typed'?"

We see a lot of talk about "GraphQL vs REST". In fact, a quick search of DuckDuckGo shows pages of results on this exact subject. Yet, pedantically speaking, the statement is a false comparison.

To be clear, those posts are typically discussing a specific class of REST server. And there are *huge* advantages in using GraphQL. Let's dig into the details to understand what's actually going on. Which will inform us to better understand when to use each one.

## Quick Review

What is REST?

According to wikipedia, is a software architectural style for web services. 

What is GraphQL?

According to wikipedia: a data query and manipulation language and runtime for APIs.

## The Types

Right from the start we should notice that these definitions are different: One is referring to an architectural style. Which is, at most, a logical design. The other is referring to a language and runtime. Which is not a style but a physical design.

Rather like comparing a Toyota against wheeled vehicles. "Toyota vs wheeled vehicles". Sounds kinda silly huh? "Toyota is a high quality implementation of wheeled vehicles" sounds better no?

Indeed, GraphQL is a high quality (but narrow!) REST interface. :)

## GraphQL <: REST ?

Neither GraphQL or REST are limited to HTTP. That said, if we focus on HTTP we will find that GraphQL over HTTP adheres to the REST architectural style! The caveat is that the range of data (the resource) from the single `/graphql` endpoint is large. Fortunately, how that endpoint behaves, the structure of the requests and response is *precise*. This precision is ensured to a degree REST cannot provide in general.

## So what is it?

GraphQL is an Interface Description Language :)

Pretty much what the wikipedia definition was! Still, it's not fair to assume it's "just another IDL". Unlike many other IDLs: GraphQL contains request composition and a clear specification of interpreter semantics. GraphQL also supports a high quality, REST compatible, transport. These are valuable innovations!

Here we also find a start for describing where GraphQL is best applied: When a precise interface description is possible and required; When the domain of client requests requires composition. This is not always the case, but covers (in my experience) a large spectrum of services development.

## Antipatterns

To continue with attempting the comparison of "GraphQL and REST" without considering the application is risky. Naively assuming, from this false comparison, "GraphQL is better than REST" can result in a variety of issues

Take a few situations where using GraphQL is questionable:

1. Serving binary data resources. GraphQL only has a single representation. Any data that is to be provided must be serialized in this representation. If there is a requirement to serve, for example, large images of various formats a GraphQL server would be costly and, frankly, re-implement a lot of REST.

2. Requirement for non-compositional requests. The composition aspect of GraphQL has a cost: The request must be interpreted accordingly. This is non trivial in general and can result in an unacceptable decrease in request cost bounds precision. As well as an increase in attack surface area.

3. Client complexity. Asymptotically, a minimal REST solution for certain applications is simpler than the equivalent GraphQL. This is an extreme comparisons tho. For most applications: reliable high quality client/server is a better choice than attempting to achieve the absolute optimal.

## Concluding the Pedantry

I hope you found this pedantic adventure interesting! In the end, GraphQL is another excellent and useful tool for our toolbox. However, let's not forget the real goal:

**To develop high quality services for our customers.**

Always keep that in mind. Never settle no matter the hype. You'll do great! :D