Most teams pick a headless CMS the way they pick a flight: by price and a feature checklist, then spend the next two years living with the seat. The regret almost never comes from the API. It comes from a content model that fought the brand, an editor experience nobody trusted, and a bill that grew teeth as traffic climbed. This is the decision we walk clients through, vendor-fair, and built to keep you from rebuilding in eighteen months.
A headless CMS separates where content is stored and edited from where it is rendered. Content lives in a back end and ships to any front end (website, app, kiosk, voice) over an API. That decoupling is the whole pitch, and a good one. But the freedom is also the trap: with no built-in front end, every decision you skip becomes one you make badly later.
What a headless CMS actually buys you
A traditional CMS like WordPress couples the editing back end to a rendering theme. A headless CMS removes the theme: you get a structured content store and an API, and you bring your own front end, usually a modern framework, often static or edge-rendered.
The upside is real. You render with the stack your team wants, reuse content across surfaces, and get a faster, more secure site because the public front end is just files or functions, not a database query on every request. The downside is equally real: nothing is decided for you, so layout, preview, roles, and workflow are now your problem.
Headless gives you a content store, not a website. Everything between the API and the visitor is engineering you are now signing up to own.
That is not a reason to avoid headless. It is a reason to choose deliberately.
Start with the content model, not the vendor
The single biggest predictor of regret is choosing the tool before the model. Your content model (the types, fields, and relationships that describe your content) should drive the decision, because every CMS makes some models easy and others a fight.
A good model mirrors your business, not a page layout. A service is a type; a case study references a service; an author references the posts they wrote. When the structure is right, your front end pulls related content automatically and editors fill in clean fields. When it is wrong, you get rich-text blobs and copy-paste duplication that rots within a quarter.
Before you compare vendors, sketch the model on paper and pressure-test it:
- Does the tool model relationships well, or fake them? References between types are the difference between a content system and a folder of documents.
- Can a field be reused across types without redefining it five times?
- Does it support localization the way you actually need it: per-field, per-document, or not at all?
- Will the model survive a redesign? Content modeled around meaning outlives content modeled around a specific page. We unpack this in website information architecture; it is the same discipline one layer down.
Get the model right and most CMS options serve you. Get it wrong and the best tool still feels like a fight.
Editor experience is a feature, not a nicety
Engineers choose the CMS; editors live in it every day. If the people writing and publishing dread the interface, they route around it. Content goes stale or ends up back in a spreadsheet, and you pay for a tool nobody uses.
Judge editor UX on the things that bite daily:
- Preview. Can an editor see the change in context before publishing, not just a raw field form? Teams underrate this most.
- Validation and guardrails. Required fields, character limits, and helpful descriptions ship complete pages, not half-filled ones.
- Roles and workflow. Draft, review, publish, and scheduling that match how your team actually approves work.
- Media handling. Image cropping, alt-text prompts, and sane asset organization, so accessibility is built in rather than bolted on. This is the same logic behind accessibility as a design decision.
Sit a real editor in front of any finalist and watch them publish a page before you sign anything.
The two families: git-based vs API-based
The headless landscape splits cleanly into two architectures, and the split matters more than any single brand. Pick the family first; the vendor is a detail inside it.
Git-based: content as code
Git-based systems store content as files (Markdown, MDX, JSON) in your repository. The CMS is an editing layer on top of git. Astro’s content collections sit in this family, which is why we lean toward it for content-driven marketing sites in why we build with Astro.
The strengths are concrete. Content is versioned alongside code, so every change has a diff, an author, and a revert. There is no separate database to host, secure, or pay for, and content in the repo makes local development trivial. The trade-offs are concrete too: non-technical editors need a friendly layer over git or they will not touch it, real-time collaboration is weaker than a hosted database, and very large content sets strain a file-based approach. Git-based shines for sites whose content is human-scale and whose editors are few and trusted.
API-based: content as a service
API-based systems store content in the vendor’s hosted database and serve it over a REST or GraphQL API. This is the larger, more familiar family, with products holding different opinions about modeling, pricing, and editing.
The strengths: polished editing, strong multi-user collaboration, robust localization, and easy scale to large content sets and many contributors. The trade-offs: you depend on the vendor’s uptime and pricing, content lives outside your repo, and versioning is whatever they gave you. You are renting infrastructure, which is fine. Just know that rent can change.
Git-based makes content part of your codebase. API-based makes content a service you subscribe to. Neither is correct; one of them is correct for your team.
A handful of editors and a few hundred pages? Git-based often wins on simplicity and cost. Many concurrent editors, heavy localization, or a content set in the thousands? API-based usually earns its keep. Commerce is the clearest case for this end of the spectrum: catalog, promotions, and checkout all surface through APIs while the storefront stays fully custom, a pattern covered in headless commerce explained. If the commerce layer itself is still undecided, how to choose an e-commerce platform works through the same framework applied to the storefront back end.
APIs and the front end you’ll actually build
The “headless” in headless is the API, so look at it directly. REST is simple and universally supported. GraphQL lets the front end ask for exactly the fields it needs in one request, keeping payloads tight on content-rich pages. Most serious vendors offer both; what matters is whether the API’s shape fits how you render.
Tie this to your rendering strategy early, because it changes the cost math. Render statically at build time and you query the CMS during the build and ship plain files: fast, cheap, resilient, but you rebuild to publish. Static output also means server-side search is off the table by default, so plan for it separately; adding search to a static site maps the options that work without a traditional back end. Render on the server or edge and you query per request: fresher content, but a harder look at rate limits and latency. Two questions save real pain later: is there a preview API so editors can see drafts, and does publishing fire a webhook that triggers a deploy? Confirm both before you commit.
Cost and hosting: read the bill before you sign
Headless pricing hides its real cost in the dimensions you do not think to check at signup. Watch these lines specifically:
- Seats. Per-editor pricing punishes exactly the success you want. More contributors means a higher bill. Model it at the team size you expect in two years, not today.
- API calls and bandwidth. Server-rendered, high-traffic sites can blow through request quotas. Static rendering blunts this, which is one more reason rendering is upstream of the CMS choice.
- Records and locales. Entry caps and per-locale multipliers turn a cheap plan expensive the moment you scale or go multilingual.
- The exit. Can you export everything in a clean, structured format? A CMS you cannot leave has leverage over you. Test the export before you depend on it.
Hosting follows the same fork. Git-based content needs no separate host; it builds and deploys with your front end. API-based content lives on the vendor’s infrastructure, so their uptime is your uptime. There is no free option here, only the trade-off you chose on purpose versus the one that surprised you. And a CMS that quietly degrades performance has a price of its own, which we make concrete in the real cost of a slow website.
A regret-avoidance checklist
Run the finalist through these before you commit. Any “no” is a conversation, but an unexamined “no” is how regret gets in.
- The model fits the business, not a single page layout, and survives a redesign.
- A real editor published a page in the trial and did not hate it.
- Preview works for unpublished content, in context.
- The API shape matches your rendering strategy and your framework.
- The two-year bill (seats, calls, records, locales) is modeled, not assumed.
- You can export everything cleanly and leave without a rewrite.
- The architecture family matches your editor count and content volume.
Clear all seven and brand loyalty is irrelevant. You have made a defensible choice. Fail several and no feature list will save you.
How Strynal approaches the decision
At Strynal, the CMS is never the first question. The content model is. We model your content around what your business actually means before a vendor’s defaults shape it. The tool serves the model; the model never bends to the tool.
We stay vendor-fair on purpose. For a focused team with a human-scale content set, a git-based setup on a fast, statically rendered front end is often the lower-regret path, and a large part of how we build websites and apps. For heavier content operations, a well-chosen API-based platform earns its cost. The senior team that scopes the work builds it, so the model, the API, and the front end never drift apart in handoff.
If you are weighing a headless CMS and want a choice that holds up in two years, tell us what you’re building and we’ll pressure-test the model with you before anyone talks vendors.