GraphQL, from a REST perspective

So, this GraphQL kid, huh, has it got no respect for its elders?

Warning: this is not a “GraphQL vs REST” post and there will be no “pick this if that” summary at the end.

An idol with clay feet

All seemed good in RESTland until we realised there were some discontent voices:

  • clients would occasionally face the need to perform dozens of API calls to populate a page;
  • hyperlink includes would be leveraged, to then generate overly complex client requests;
  • latency and data volumes on both approaches would be a killer, especially in a mobile world;
  • BFFs can then be brought in, but in a world where you have one BFF per client, where’s your reuse?

The usual response is, unsurprisingly, “this is an API design problem.” While this may be true, it begs the question: can’t we address these issues with an approach that effectively discourages them?

This is what Facebook set out to do, by breaking the pervasive REST(ish) thinking.

Birth of a contestant

So, what do you do when you break the mold? Go back to square zero and build from there:

  • they built a language, not an architectural style. While Roy Fielding’s dissertation on REST goes into way more detail about architecture than on how to structure requests and responses, the GraphQL spec provides unambiguous detail on contract with zero definitions for the underlying implementation and design;
  • they optimized for their use cases. Easy on mobile? Check. Side by side spec for convenient UI binding? Check? Oh, you do social networks, right? So let’s make this a graph language.

So what do you get with that?

  • Better DX/UX: the ability to populate your app with the exact data you need using one API call is greatly TK ADVERB convenient and can provide snappier responses to end users;
  • Better evolvability: I’ve written about this before TK LINK TO PREVIOUS POST and will probably do it again, but the decision to mandate clients to specify each field they require makes for an easier API evolution;
  • Well defined schemas: we will not see a battle for specs as we saw in HTTP APIs (swagger/openAPI won, although one could argue that approach is not truly restful), as the language was born with a schema definition.
  • Server pushes: GraphQL has the inherent concept of subscription, that allows servers to push events to clients with an underlying mechanism of your choice (eg: web sockets). We will dive in into this in a later post.

Still no silver bullet

Ok, so if you get all these goodies, ditching REST in favour of GraphQL is a no brainer, right? Not so fast:

  • caching becomes way less trivial, as we cannot benefit any more from standard HTTP functionalities such as etags. Having said that, it’s still doable;
  • you still have to design with your clients in mind and BFFs may still be necessary;
  • many people talk about versioning as well, but if you are doing true REST then you are also taking an evolution over versioning approach anyway;
  • you lose the full benefits of HATEOAS: achieve this holy grail and you have a level of API navigability and extensibiy you would not get with GraphQL;

Take this with a grain of salt (as it’s an opinionated statement), but the last bullet point is the only real significant con: there’s a lot to be gained with HATEOAS.

Having said that, the fact still stands that the concept has been out there for many years and few APIs have reached this nirvana.

The king is dead, yadda yadda

REST advocates (present company included) dreamed of a world where diverse APIs would be stitched together by means of hypermedia. This could be the long awaited push we’d need for a truly semantic web.

The reality, though, is that immediate problems were being neglected and this may become the downfall for REST’s popularity.

Ok, now, which one is better?

Nope, no such a thing here. I did warn at the beginning, though. Anyone arguing objective superiority is probably too biased and most recipes for decision making oversimplify matters. This is an important enough decision to justify deep reading and a fair amount of spiking.