REST and GraphQL, explained without the jargon

Every audit we run turns up some version of this. Here is REST and GraphQL without the vocabulary that usually surrounds it.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Doing this properly once is usually cheaper than doing it approximately three times.

The short version

REST is simpler to cache and easier to reason about. Small and consistent beats large and occasional here. It is the sort of thing that looks like polish right up until it costs you an enquiry.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. There is a version of this that is over-engineered, and it is worth avoiding.

GraphQL shines when clients need wildly different shapes of data. None of that requires a large budget, only a decision and someone to own it. Assume whoever inherits this will have half your context and none of your patience.

Making it stick

The right answer depends on your clients, not on fashion. The cost of getting this wrong is rarely visible on the day it happens. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

The short version

Most development decisions are really maintenance decisions wearing a different hat. 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

If you want a second opinion on how yours is set up, ask.