TL;DR

From a short time using GraphQL APIs I sense that there’s a ‘GraphQL Way’ for how things should be. A set of promises that the technology makes to its users. But those promises are frequently being broken, or at least undermined, as people rush to create GraphQL end points without perhaps investing enough time and effort into how things should work. The causes of this woe are mostly things we’ve seen before, as previous waves of new stuff have swept through the industry; so of course the remedies are much the same as ever, and it starts with building a picture of what good looks like.

Background

I’ve been using a few GraphQL APIs over the past year or so, and many that I’ve encountered fall short of the expectations set by the Introduction to GraphQL. This leads me to think that there is a ‘GraphQL Way’, but maybe it’s not yet easy enough for API developers to follow it.

Recent conversations with James Governor, Fintan Ryan, Paul Johnston and others such as this Twitter thread make me think that there’s a need to better articulate what good looks like. This post is intended to get the conversation started. I’m not a GraphQL expert, just somebody who has to use APIs and often finds themselves thinking ‘this could be better, this should be better’.

YOU ARE IN A MAZE OF TWISTY LITTLE PASSAGES, ALL ALIKE.

Colossal Cave Adventure

That’s how I often feel when trying to navigate a GraphQL API. The thing that you want should be through the next door, but after going through 3-4 doors you’ve circled back in the graph to the place you were a few steps back, with no sign of the grail of enlightenment.

The promises

GraphQL makes a number of implicit promises:

1. Ask for just the data you need, get back just the data you need

GraphQL is pretty good at realising this promise, which makes it great for its original purpose of more efficient communication between mobile apps and their backend services. It’s less chatty, and more verbose, which are both good things when you’re worried about latency, data consumption and network flakiness.

Previous APIs developed a nasty habit of serving up giant JSON documents, expecting them to be cut down to size by the client; whilst GraphQL lets you just get the bits that are needed.

2. Self describing

GraphQL APIs can serve up their own schema, which should be enough to help users of the API find what they need. They have the map, so it should be easy to find the treasure.

That’s fine, provided that the map makes sense, to people other than those who made the map. If the schema is just another way of shipping your org chart then it could be dysfunctional. If it’s full of unexplained internal references then it might be incomprehensible. Self describing only works if the description makes sense (to a newbie with no other context to grab onto). James Scott explores this in ‘Is GraphQL really self-documenting?‘.

Michelle Garrett recently talked at QCon London (link to follow once they get around to publishing) about the lengths taken by the Twitter GraphQL team to curate a schema that makes sense. This stuff doesn’t just happen, it takes work, and care – governance.

The good bit is that we’ve come a LONG way from Web Services Description Language (WSDL) and Universal Description Discovery and Integration (UDDI), and this time it’s clear that self describing can work (beyond standards org slide decks and out in the real world).

3. Filtering

GraphQL APIs should allow a request to specify a filter. But many implementations don’t actually implement that capability. This ends up breaking some of the first promise, as you now need to ask for everything and do the filtering locally. At least (with promise 1) GraphQL queries are specifying which nodes/fields you want back, so you’re not having to filter through all of everything, just some of everything. It’s not pretty though, and can quickly run into needing pagination where previous REST based approaches spared that.

The causes

Why do the promises get broken?

New shiny

There are lots of GraphQL implementations popping up that are the first time doing this for the teams involved. They’re inexperienced, don’t necessarily know what good looks like, and easily walk into minefields without noticing the warning signs.

CV++

Resume Driven Development bedevils the entire industry, and because GraphQL is the new shiny there are an awful lot of new GraphQL end points getting created to bolster CVs and LinkedIn profiles.

REST inertia

Where there’s an existing REST API there’s a risk that a new(er) GraphQL API will try to repeat the same story in a slightly changed dialect. The promises of GraphQL don’t come true by adding a new end point, they have to be underpinned by some (re)thinking about design and purpose.

Not used internally

If you’re creating a new API, and it’s just for external customers, and not being used internally; then something is wrong. Badly wrong. And you likely won’t be getting the immediate feedback to make things right; just lots of whinging and moaning off in the distance.

Making it better

There are of course ways to help ensure GraphQL implementations live up to the promises:

Documentation, Samples and Examples

My colleagues hear me say those words almost every day, and I say them because good documentation, samples and examples are generally the difference between something that’s accessible, easy to use, and scores mass adoption, and something that’s none of those things.

Even if it’s obvious to you the creator of the new super smart self describing GraphQL end point how every last drop of valuable data can be wrung out of it on demand; some samples and examples of that brilliance will help some of us less sharp people get to our ‘aha’ moments more quickly and easily.

Pave the golden path

There’s a lot of good stuff out there already to help people implement their GraphQL services, and corresponding good stuff to help people consume those services. But maybe there’s scope for more help with design considerations, the questions of ongoing schema governance, and helping people keep the promises of GraphQL.

Tooling might help here. But also pausing for a moment, thinking, running some experiments and getting feedback. Asking what good looks like, and charting a path there. Proper software engineering.

Conclusion

GraphQL APIs are coming into the mainstream, and as they do so they’re often breaking the promises made by the underlying technology and its proponents. That’s happening for a slew of fairly predictable reasons; which is why the remedies also look so familiar. We can do better, we should do better.