Everything I know about good API design

In 2025, leaving GraphQL out of a discussion on modern API design is like writing about web frameworks and downplaying React. It may not be right for every use case.. but it has become foundational in many serious frontend/backend architectures, and that deserves acknowledgment.

GraphQL isn’t just another protocol. It’s a paradigm shift in how we think about designing and consuming APIs. The author downplays its role, but in practice, GraphQL enables cleaner contracts between frontend and backend, encourages typed schemas, and dramatically reduces over-fetching and under-fetching. That’s not a minor point .. that’s central to what most developers care about when consuming APIs.

Regarding caching: yes, REST has traditional browser and CDN-based caching, but GraphQL is absolutely cacheable too. Tools like Apollo Client and Relay have built-in normalized caches that are far more granular and powerful than most REST setups. At the infrastructure level, persisted queries and CDN layer solutions (like GraphCDN or Stellate) further optimize caching behavior. So the claim that “you can’t cache GraphQL” is outdated at best.

Caching is straw-man. Complexity tends to be higher to implement a graphql backend than for e.g. type-spec => openapi backend. For the simple case the simpler solution wins imo. For the complex case it can be a toss-up, but it seems that performance and security can be a big deal-breaker for graphql, so maybe only big enterprises can afford to go down that route.

I'm not sure what you mean by the react analogy, react seems to be far more popular than graphql in their respective areas.

GraphQL has some impressive points, but sometimes feels like it shifts too much control to the client. I'm on the fence about it.

There are performance footguns (like recursion, for which you'd have to consult your GraphQL server library for mitigations). There is often a built-in 'introspection' endpoint, which many consider a security faux-pas (to which I disagree — I think it's pretty noble, like having built-in OpenAPI docs) BUT you can easily craft a recursive query using just this endpoint that will take (some) GraphQL servers down. There are plenty of posts written on the matter and I'm sure there are mitigations, but my first exposure to GraphQL was on someone else's project (a respectable engineer who I consider very skilled) and within the first day I had noticed this intriguing structural hazard and taken the server down...

It therefore seems to be a tool that is possibly difficult to 'hold correctly'; at least people should be cautious about going in without doing their research about these things. Probably a maturity issue, but one that people ought to be aware of?

Other gripes:

It's displeasing how the HTTP status code does not correlate with the actual success response of the API, which makes typical request logging less useful.

I guess it also makes it harder to provide optimised hot paths on the server (because your client team might shift their queries around, or whatever).

In previous experience I also find that having easily-recognisable names for API endpoints (like `GET /repositories`) makes talking about them, and recognising them, easier than the more-opaque-feeling GraphQL approach.