A short guide to REST and GraphQL

We end up explaining this on discovery calls often enough that it deserved writing down. Everything we would tell a client about REST and GraphQL in the time it takes to drink a coffee.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Assume whoever inherits this will have half your context and none of your patience.

The reason this keeps coming up

REST is simpler to cache and easier to reason about. In practice this is a scheduling problem more than a technical one. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

How to approach it

GraphQL shines when clients need wildly different shapes of data. The teams that handle this well are rarely the ones with the biggest budgets. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Common failure modes

The right answer depends on your clients, not on fashion. It is worth being explicit about, because assumptions differ quietly. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

How to tell if yours is fine

The question is rarely whether something can be built, but what it costs to keep running afterwards. Three things worth confirming about REST and GraphQL before you move on:

• Someone can say what the current setup is without going to look
• GraphQL shines when clients need wildly different shapes of data — and you know whether that is true here
• There is a way to tell whether the last change to this helped

The point is not perfection, it is knowing which of these you have consciously chosen to skip.