10 posts tagged with "Best Practices"

GraphQL specification editions used to arrive every few years: 2016, 2018, 2021. The September 2025 edition ended a gap of almost four years, and the September 2026 edition follows twelve months later. It is a smaller release than September 2025, which ratified @oneOf and schema coordinates. Its changes are careful ones that matter more than their size suggests, including a new definition of what fragments are for. That one made us look again at a post we published in 2025.

Send a GraphQL server a document with a typo in it, and for most of the last decade the answer came back as 200 OK. Ask for a field that does not exist, and you got 200 OK. Run a query that half worked, and you got 200 OK again, with the bad news inside the body. Load balancers, CDNs and dashboards do not read response bodies, so to them all three requests looked like successes. The GraphQL over HTTP specification is getting its first edition, named September 2026, and its main job is to let the status code tell the truth again without breaking the clients that learned to ignore it.

Every GraphQL talk eventually arrives at the same slide: "GraphQL doesn't need versioning." The audience nods. The speaker looks pleased. And somewhere, a team is about to learn the hard way that "doesn't need versioning" is a bedtime story we tell each other to avoid discussing the actual versioning strategy GraphQL requires. Spoiler: there is one. It's just embedded into the schema instead of the URL.

Every few years, the API wars get a new challenger. REST fought GraphQL. GraphQL fought gRPC. Now GraphQL is fighting tRPC, and a loud corner of the TypeScript community insists we can finally delete GraphQL from the stack forever. They're half right, half wrong, and half neither (yes, that's 150%; API debates don't always add up). Here's the honest comparison, the scenarios where each genuinely wins, and a reminder that this debate is only meaningful for a specific slice of the industry.

Here's a sentence that should terrify anyone running a GraphQL API in production: "Our iOS app sends arbitrary query strings to our server, and we just trust them." You wouldn't let your web app send raw SQL. You wouldn't let a mobile client dictate the shape of a REST response. Yet for some reason, we've collectively decided it's fine to let clients write GraphQL queries of any depth, width, and cost, and we'll just sort it out at runtime with complexity analysis and rate limits. Persisted documents are how mature GraphQL teams fix this, and in 2026 there's finally enough consensus to do it properly.

For a decade, GraphQL responses came back as one lump. You asked for a page, you waited for every field to resolve, then the server wrapped it up and sent it over the wire in one envelope. Fast fields waited for slow fields. The whole response moved at the speed of its slowest resolver. Then @defer and @stream arrived to fix exactly that. They've been maturing as a proposal for several years - deliberately, because getting incremental delivery right is genuinely hard - and they're now real enough to use with modern clients and servers. The open question is when they pay off, and both camps have a case.

Two camps. One schema. Endless arguments on Twitter. Every Java GraphQL project, within the first week, has the same meeting: should we write the schema first in SDL, or should we write Java classes and let the schema fall out of them? Both camps are convinced the other is doing it wrong. Both are partially right. Here's the honest breakdown, the actual tradeoffs, and what the 2026 Java ecosystem looks like when you stop arguing and pick one.

For a decade, we've told ourselves a nice story: GraphQL is for humans and frontends. Schemas exist so React developers can autocomplete field names. Then 2026 arrived, LLMs started writing half the code in your repo, and it turns out the thing AI agents desperately needed was exactly what you already had sitting in schema.graphqls. Every typed field, every enum, every nullable flag, every input validation: a ready-made contract for an agent to reason against. You just didn't call it that.

Your GraphQL schema looked perfect on day one. Clean types. Tight enums. Non-null everything because you were sure those fields would always be there. Then requirements changed, a service went down, and your schema went from "elegant contract" to "active crime scene."

This is a post about evolving GraphQL schemas without making your clients hate you.

You're copying the same fields across 17 different queries. Your code reviewer is crying. Your future self is plotting revenge. Enter fragments: the DRY principle applied to GraphQL queries.