A contract you usually inherit, not choose
Technology
GraphQL is a typed contract between a client and a schema. You ask for the fields you need, you get exactly those, and the shape is validated before the query runs. On most of our projects nobody sat down and chose it. It arrives with the vendor: DatoCMS serves content over GraphQL, Contentful offers it alongside REST.
We use it mostly at build time, pulling structured content into statically generated pages, and at request time where a view composes data from more than one source. The typed schema is the part we are actually buying. Against a single backend with a handful of endpoints, the graph is overhead you have to justify.
Why
Where a typed graph pays for itself
- The schema is the type system
Code generation turns the schema into types the editor and the build already check, so a renamed field fails the build instead of the page. CrewAI renders every layout from Contentful through GraphQL with strong type safety, which is what keeps designs consistent across a platform.
- Composition happens in the query, not the client
A page assembled from reusable sections asks for the union of what those sections need, once, including nested relations. The alternative is a request waterfall the browser discovers one hop at a time, which is the failure mode that makes composable sites feel slow.
- Overfetching moves, it does not disappear
The client stops asking for fields it will never render. The resolvers behind those fields still run, and a nested selection over a list can quietly become one database call per item. You saved bytes on the wire and moved the cost onto the server.
- Caching is harder than REST, by design
A REST URL is a cache key every CDN already understands. A GraphQL query is usually a POST body that shared caches will not touch, so you trade that for normalized client caches and persisted queries. Both work. Both are more machinery than an ETag.
- A schema outlives the frontend that prompted it
Once a client is deployed against a field, removing it breaks that client. Versioning becomes deprecation and patience rather than a new URL. We model schemas expecting them to survive the redesign that created them, because they usually do.
- Sometimes the answer is to sync, not to query
For CLS Health we pulled provider data from the Kyruus Health API into Prismic using integration fields, syncing every 30 minutes, instead of querying it on every request. Editors work in one system and the page stops depending on somebody else's uptime.
