Net API Notes for 2019/02/14: GraphQL and Power Users


Last week I was in San Francisco. This week? New York City. This year has gotten off to a hectic start. Despite this, however, I continue to try and play with as many API approaches as possible. I recently had the chance to dig deeper into GraphQL.

I last spent a bit of editorializing about GraphQL in September of 2017. At the time I lambasted, what seemed like, a healthy dose of FOMO-driven development. I also shared some resources for developers to make more informed decisions. Most recently, I took the Samer Buna Pluralsight course entitled "Building Scalable APIs with GraphQL".

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".

A sampling of power user interfaces.

(Special thanks to Joseph Gardner for provide examples 1 and 2)

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.

In December, I highlighted Mark Foster's presentation on client-driven APIs. There, he argued, GraphQL enabled clients to create exactly the experience they needed. Like power user interfaces, an incredible amount is exposed and available. It avoids a lot of the 'bedeviling' conversations required by design, the kind of use case gathering and product design thinking that are separate skill sets from development.

The 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.



Along these same lines, Matt McLarty has a powerful piece posted at InfoQ entitled "Overcoming Restlessness". Lot of great points there, but I'll let his words summarize it best:

"Instead of seeking to replace REST, the software engineering industry should seek to evolve by building on the maturity of the REST ecosystem while exploiting the technological strengths of the new protocols."


In a well crafted API design, clients should have the information available to make smart decisions. Ryan Baker has a great piece on "Crafting Beautiful UX with API Requests. If you are looking to up your design game beyond resources design, check out Ryan's thoughts on timeouts, minimum wait times, and retries.


Lorna Jane has slides and video available for her presentation, "Working with Webhooks. In the rush to adopt streaming architectures, and specific implementations like Kafka, developers may have overlooked more straightforward ways of achieving real-time results. What's more, things like webhooks leverage existing technology stacks. Lorna's piece provides a nice introduction along with some things to be aware of, like security.


A lot of folks are doing microservices. They are a way of reducing the amount of communication overhead when developing software to the bare minimum. But one can't forget cross-cutting concerns, like security. In some respects, smaller deployables mean fewer places for gremlins to hide. But it also means an overall increase in ingress/egress footprint. Sam Newman has slides and video available for his talk, "Insecure Transit - Microservice Security (I'd advise watching the video, as the slides themselves aren't quite standalone).



This newsletter I've got a couple of job opportunities to share. The first is with a team I work with out of New York City. If you are a product manager (or looking to make the leap to product management) and are interested in a product with enterprise wide impact, check out the job description.

I'm also hiring a Principle Data Analyst. There is a generic "evergreen" job description available. However, if you're interested, ping me and I'll send you the more detailed version.

If you're looking to connect with other API practitioners, check out Something missing? Reach out and let me know; I'd be happy to add to it.

Finally, a thanks to my Patreon sponsors. Their support of this newsletter,, and more is appreciated.

Till next time, Matthew

@libel_vox and

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.