GraphQL is powerful, but the experience isn't designed

18 Aug 2019 in Tech

I've had this snippet from Matthew Reinbold saved in my inbox for the longest time. It's such a good analogy that I had to replicate it here so that I have something to share when GraphQL is proposed as the all-in-one solution once again by an engineering team.

The below came from Net API Notes, Matthew's newsletter (emphasis mine):

One thing that GraphQL nails is the initial developer experience. In no time, I was poking around popular GraphQL APIs with GraphQLHub. I had live data in a few minutes. As a Time-to-First-Hello-World (TTFHW) metric, that experience is pretty powerful. Because REST is an architectural style, not a prescriptive implementation, the lack of uniformity would make a RESTful equivalent difficult.
After that glowing initial experience, the arguments for GraphQL fall into one of two categories:

  1. Clients get only exactly what they want (no transformation, over/under fetching, or chains of API calls)
  2. It is faster over the wire because of smaller, purpose built payloads (although, if you think about it, this is really just a side affect of #1)

Going beyond that, however, things began to escalate. Many arguments for GraphQL tout how clients, without transformations, over/under fetching, or chains of API calls, get exactly what they want. But it was this "put everything on the client" that began reminding me of "the power user interface".

Complex Power User Interface

Sure, this type of interface is powerful. I don't dispute that. But it isn't approachable, or catering to a use case. In short, it isn't designed.


GraphQL, like in the case of GitHub, makes sense because its user base are power users. They are already deeply intimate with the inner workings of that system. In other cases, like when React JS is acting as the front end, the tech stack is dictated to folks.

We can raise a set of API creators with a better grasp of "digital" design and product thinking. Or GraphQL might expand beyond situations where the client is required to have intrinsic knowledge of the API's domain. It will be fascinating to see where we go from here.