REST API Notes for 2016/09/15: GraphQL

As I write this some of the most driven, diligent, and delightful personalities in the RESTful API space have gathered in Greenville, SC for RESTfest. Starting with an all day hackathon, the select participants are collaboratively working through some of the thorny issues surrounding API development. If you, like me, couldn't make it this year, they have a live stream. Hashtag camping is also always an option for these sort of events.

Despite some of the best minds absconding to their remote retreat, however, the API news keeps coming. Let's switch gears to the major brew-ha-ha this week:


GraphQL is a data query language developed for internal Facebook use in 2012 and publically released in 2015. It comes with an API allowing for queries to be executed over HTTP. But it has only been making waves recently. Kin Lane, the API evangelist, implied that GraphQL's existence was counter to quality API design:

"GraphQL feels like the DBAs coming out from behind the firewall and rather than adjusting to the world, they are implementing their way of doing things on everyone — which is classic IT/backend behavior. No average user will ever use GraphQL interfaces, where they will copy / paste a URL and put it to work for them — if it is intuitive."

A day later he softened his stance. Then, this week, GitHub announced their API would be available through GraphQL; they claim it is "the biggest change to the API since we snubbed XML in favor of JSON".

The flurry of opinions in the last week for a technology that has "been out there" has left some of us flabbergasted (and by us, I mean me). There's a number of lessons to be learned here. The first is never underestimate the legitimacy a beloved brand can bestow upon a technology. I guarantee that there were developers who had would never consider GraphQL as a viable solution until they saw GitHub's announcement.

The second lesson is that some developers, like those creating tightly coupled solutions, find this pattern attractive. Not everyone is trying to create the next Stripe or Twilio; consumption by thousands of external developers is not a priority. They may be simply trying to pipeline information from internal systems to their own support applications. They're using HTTP(s) because the protocol is ubiquitous but their audience is not. Domain knowledge is already shared between the API producer and consumer. Thus GraphQL is easier.

The third lesson is that it is really fun messing with Stevie Graham. While I take his point that REST APIs come with their own set of constraints, some that may be orthogonal to developer wishes, it isn't about one approach or another "winning". And, to my first point, it isn't about making technology decisions because it is the thing in the news at a given moment.

If GraphQL solves a need that you've been struggling with, then great. However, "resume-driven-development" is real. If a direct report is saying that you need to adopt GraphQL or "be left behind" I've hopefully given you a few resources to probe that sentiment. It is the responsibility of decision makers to understand where GraphQL falls for them.

The reason I decided to share my notes about RESTful API design was to help developers, architects, and business folk have the best information at their fingertips for making informed technical decisions. It was never about aggregating every thinkpiece or drafting off the latest trend. I try to share noteworthy angles or nuance worth the attention. When I get more of that, GraphQL or otherwise, I'll be sure to pass it on then.

Till next time,

Matthew (@libel_vox)

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.