REST API Notes for 2017/09/05 - GraphQL (again)

Hopefully separating the vim from the vinegar that GraphQL represents doesn't become an annual September tradition. Last year, about this time, I recapped the 2016's tempest in a teapot. Fast-forward a year and, other than the barbs being sharper and a couple of notable releases, little has changed.

In my day job, I lead an API Center of Excellence. My team's responsibility is maximizing the business value of developer's efforts. While we started with web-based (or, on a good day, RESTful) APIs, we quickly realized that not all problems required an API solution. That is a profound distinction from what I've seen elsewhere. As Abraham Maslow observed in 1966: "when all you have is a hammer, everything looks like a nail". If our team is only here to dictate API solutions, then we're doing a disservice to our developers, our company, and, eventually, our customers.

But that isn't a green light for a technology free-for-all. A team recently submitted their API intent, in OAS compliant form, for review. In the place of detailed documentation about business objectives, endpoints, status codes, and payload, however, there was a single POST. In the POST body was a single parameter, named "query", defined as a "string" type. When questioned, the submitters stated that they were "doing GraphQL". Why GraphQL? Because it was "taking over" and they didn't want to be "left behind".

This is frustrating on a number of levels. As I tweeted, "FOMO is NOT ARCHITECTURAL GUIDANCE". Further, they failed to make a rational argument why this was the best approach for their unique problem (or, more importantly, how they will overcome the downsides of the trade off they're proposing).

Scott Bellware is one of the more entertaining and vocal critics of GraphQL. While I hate reposting so much of what he shared, it's too good not to republish his recent tweetstorm in bulk - while humorous, he is getting at nuggets of inconvient truth:

"How can we make HTTP APIs even worse than they are now? Hmmm. Oh! I know! Let's make them support non-deterministic queries. Yeah!"

"What we're seeing in the rush to GraphQL is a failure to establish the inflection point where it's long term cost-beneficial"

"The regularity I most see with GraphQL adoption is Web MVC devs who've never conceived of anything beyond monolithic relational databases

"'What if my HTTP interface could process any request for data,' is not a problem that needs solving. It's a symptom of a worse problem."

"Solve a problem with an open data API. Now you've got a near infinity of permutative coupling problems."

"Before you adopt Technology X because 'REST failed you', take a moment to consider whether or not it was REST that you were doing.

"And yet, the vast majority of web devs proceed as if a resource is an http interface to an ORM object"

"If you think GraphQL solves the problems of REST, it's very likely you never understood what REST is (and maybe you should stop - just stop)

"HTTP over ORM is not REST. It's a hideous abomination that takes the monstrous implications even further in the form of GraphQL."

"I'm almost ready to assert the presence of GraphQL indicates little experience with service architectures"

There have been some very good, well-reasoned comparisons for developers (and their management) to properly assess the pros and cons. I appreciate Arnaud Lauret's approachable comparison and contrast between web-centric APIs and GraphQL. Sumit Sarkar has a solid piece comparing GraphQL to previous query syndication models, OData and ORDS. Finally, Mark Boyd has published a 'GraphQL State of the Market Report' that is worth a read.

If, conversely, I'd discourage people from seeking their strategic architectural advice from pieces proclaiming anything "is taking over", "winning", or "killing" whatever came before. Clickbait hyperbole can be fun, even entertaining. But it is a helluva lousy way to build long term business value.

Subscribe to Net API Notes

Don’t miss out on the latest issues. Sign up now to get access to the library of members-only issues.