REST vs GraphQL for a headless CMS: which should you pick?

TL;DR#

Use REST for most content sites. It's simpler, HTTP-cacheable, and has no query language to learn. Reach for GraphQL when clients must reshape deeply nested data in one request. Either way, avoid GraphQL-only CMSs that force the paradigm on every consumer of your content.

Short answer: REST is the simpler default for most content-driven sites; GraphQL earns its extra complexity when a frontend needs to reshape deeply nested, relational content on its own terms. Neither is "better" in the abstract. They solve different problems. One thing deserves a blunt warning: a CMS that only speaks GraphQL, with no REST option, forces that choice onto every team that ever touches the content, whether the project needs it or not. That's a real lock-in risk, and you should weigh it separately from which API style you'd pick if you were starting from scratch.

REST vs GraphQL in 60 seconds#

REST exposes content as a set of fixed endpoints (/articles, /articles/:slug, /categories), each returning a predictable, documented shape. You fetch a resource, you get that resource. Most headless CMS REST APIs soften the classic REST complaint (fetch too much or too little) with query params for field selection, filtering, and relationship expansion, but the endpoint's basic shape is still fixed.

GraphQL exposes a single endpoint and a schema. The client writes a query describing exactly which fields and nested relationships it wants, and the server returns exactly that: nothing more, nothing less, in one round trip. That flexibility is the whole pitch, and it comes with real setup cost: a schema to define, resolvers to write or generate, and a client library to take advantage of it.

Both are legitimate ways to expose content. For a CMS, the deciding question isn't which is more powerful. It's which one matches how your frontend needs to consume content, and whether the CMS forces one or lets you choose.

Where each wins for a CMS#

The over-/under-fetching tradeoff is the one most often cited in REST-vs-GraphQL comparisons. Industry commentary, including dotCMS's own writeup for content teams evaluating the two, generally frames it this way: without relationship-expansion params, REST can mean multiple round trips to assemble a page (article, then its author, then related articles), while GraphQL gets it in one query. That comparison tends to underweight the other side of the ledger. REST's fixed URLs are what make CDN caching, browser caching, and curl-based debugging work without any extra infrastructure. GraphQL's single POST endpoint has to reinvent that with persisted queries or a smarter client cache to get back to parity.

This isn't a new argument, either. Drupal's "API-First" initiative, which Dries Buytaert (Drupal's founder) wrote about at length as the project decided how to expose content over HTTP, landed on JSON:API (a REST-flavored spec) as the officially recommended, in-core solution for most decoupled sites, while keeping GraphQL available as a contributed module for teams with more complex query needs. The reasoning tracked the table above: REST covered the common case with less setup; GraphQL stayed available for the cases that needed its flexibility.

The GraphQL-only lock-in risk#

Some CMSs don't give you the choice. Hygraph, for one, is GraphQL-native by design and doesn't expose a REST alternative; its own FAQ states this directly (hygraph.com/faq). If you pick a GraphQL-only CMS, every consumer of that content inherits the decision:

• Every frontend needs a GraphQL client rather than a plain fetch call.
• Every internal script (a redirect checker, a content-audit tool, a one-off migration) has to construct a GraphQL query instead of hitting a URL.
• Every teammate who wants to curl an endpoint to see what's in the CMS can't, without learning the schema first.
• Every AI agent or automation reading your content programmatically has to be taught GraphQL's query syntax before it can do anything useful.

None of that is disqualifying if your team is GraphQL-fluent and your content needs the query flexibility. But it's a real switching cost, and it's separate from the pricing lock-in most CMS comparisons focus on. Moving off a REST API means re-pointing a URL. Moving off a GraphQL-only API means rewriting every query your project has ever written against it.

Recommendation by use case#

• Blog, marketing site, docs site, most content-driven pages: pick REST. The content shape is usually stable enough that field-selection params solve the over-fetching problem, and you get CDN caching for free.
• App with deeply nested or highly relational content, or multiple frontends pulling different slices of the same content (web app, mobile app, partner API): GraphQL's single-round-trip flexibility earns its setup cost here.
• Small team without dedicated frontend/API tooling expertise: REST. Fewer moving parts, and anyone who's called an HTTP API before can be productive right away.
• A public API you want scripts, no-code tools, or AI agents to consume with zero setup: REST. Documented endpoints and a curl command beat a schema anyone has to introspect first.

Not sure which you need? Start with REST. It's easier to add a GraphQL layer on top of a REST API later than to bolt REST support onto a GraphQL-only CMS that was never built to offer it.

Adapto's REST API#

Adapto is a REST API CMS: content comes out over documented REST endpoints. See Adapto's Articles API reference and pagination and filtering for how field selection and relationship expansion work in practice. There's no GraphQL-only wall to get past, and no query language to learn before you can fetch a page of articles.

A note on scope: that REST API is read-only. It's built for content delivery, serving GET requests against endpoints like /v1/articles, /v1/articles/by-slug/{slug}, /v1/categories, and /v1/pages, authenticated with an x-api-key header, all returning the same paginated { items, total, page, limit, pages } shape. Creating, updating, and deleting content doesn't happen through the API at all. It happens through the adapto CLI, which is built for CI pipelines and AI-agent workflows: content changes go through a scriptable, reviewable command rather than a write endpoint sitting on the public internet. For the job this article covers, pulling content into a frontend without a GraphQL schema in the way, that's what the REST API does.

If you're setting up content types before you get to the API layer, structuring content models that scale covers the modeling side: references, components, and the mistakes that make either API style harder to work with later. And if REST-vs-GraphQL is one line item in a bigger evaluation, how to choose a headless CMS covers where API style fits alongside pricing, seats, and lock-in risk generally.

FAQ#

REST or GraphQL for a headless CMS?#

For most content-driven sites (blogs, marketing sites, docs), REST is the simpler default: fixed endpoints, HTTP-native caching, and no query language to learn. Reach for GraphQL when your frontend needs to reshape deeply nested, relational content differently across multiple clients (web, mobile, partner API) in a single request. Whichever you lean on day to day, the CMS itself should support REST at minimum. GraphQL-only forces the paradigm on every consumer, whether they need it or not.

Is GraphQL-only a lock-in risk?#

Yes. If a CMS only exposes a GraphQL endpoint, with no REST alternative, every consumer of your content has to speak GraphQL: every frontend, every internal script, every teammate who wants to curl an endpoint, every AI agent reading your content programmatically. Hygraph confirms this directly in its own FAQ: it is GraphQL-only, with no REST option (hygraph.com/faq). That is a real switching-cost lock-in, separate from any pricing lock-in. Moving off means rewriting every query rather than re-pointing a URL.