"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.
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.
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. :)
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.
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.
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:
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.
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.
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.
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