Introduction

In this presentation, Phil Sturgeon provided an excellent debate on the pitfalls of GraphQL. This is very refreshing since the marketing web site of GraphQL does attract the lights as the new modern way of approaching API designs. Phil argues on the side that we should be making educated decisions.

On the topic of educated decisions, a lot of distinguishing factors are made about the differences between REST and REST’ish services because the two often gets confused. Most of us experience REST’ish services - therefore, we then conclude that we know everything about this architectural style.

All the notes below are some of the key takeaways from Phil’s presentation. He also made it into a blog post.

False Advertised Differentiations

There are a few key claims made by GraphQL about the lack of features in REST. Some were discussed as listed below.

1. GraphQL will only give you what you request. However, REST services can provide the same interactions via sparse fieldsets or partials.

   A client MAY request that an endpoint return only specific fields in the response on a per-type basis by including a fields[TYPE] parameter.

2. GraphQL would allow the query to return multiple resources at once via aliases. This feature is called compounded documents.

   To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called “compound documents”.

To the extreme on very complicated shaped GraphQL queries, these resources may not be on the same parity; but, this flexibility has other hidden costs which GraphQL has ignored.

History of GraphQL and its Goal

Facebook engineering first developed a language over REST which was called Facebook Query Language (FQL). However, they ran into a problem where endpoints needed to be duplicated twice so that the classical-REST endpoint could mimic the same behavior.

The design goal of GraphQL was defined on how to extract the minimal amount of data over limited data pipelines. It achieved this by becoming opinionated on the components on how API’s are developed on the server.

However, not being able to estimate the shapes of the queries of the GraphQL is a hindrance to database optimization. Unlike Facebook, the common developers don’t work for an organization who can dedicate entire buildings to solving the unknown query problem.

GraphQL also decided that it was going to forgo control protocols which exists on top of the HTTP pipeline. This should be considered a disadvantage.

REST vs. REST’ish

Phil does return back to why GraphQL is attractive to the REST veterans. It is simply due to the careless thought processes on how REST services are built.

• REST is not about providing links over the wire.
• REST stands for REpresentational State Transfer) which means that links off documents are about which actions are allowed, and does not allow each client to infer based on properties from the JSON response.

Phil also expands a little bit on how various endpoints could be built by some kind of template building mechanism.

Caching Control

Lastly, a lot of content covers caching. In essence, Phil encourages maximising the probabilities of cache hits over the HTTP control pipeline so that even internet proxies are able to serve the traffic instead of your own backend. Genius!

As Phil mentions, the only chance that your API may achieve this cache control is to ensure that each client requests the same URL. Because of the dynamic nature of GraphQL, cache control is infeasible unless you get proxies to be smarter. This also happens to be a good argument against using sparse fieldsets in REST services!

The thing though - what is a good strategy for cache invalidation? I feel that this does become a largely unanswered topic across all stacks.

Conclusion

Understanding and appreciating the differences between REST vs. REST’ish vs. GraphQL may be appropriate to make a good argument for and against each approach.

REST is more flexible in the long-term whilst the GraphQL is akin to what REST’ish services may appear. We should be aware that the new tool is indeed an evolution, and that we do not misuse the tools, in order to prevent time-wasting.