Headless WordPress

Headless means WordPress stops rendering pages. It keeps the database, the admin and the editing experience; a separate application fetches content over an API and renders the front end. The theme layer is removed entirely.

That is the whole idea, and it is a bigger change than it sounds — because a great deal of what people value about WordPress lives in the layer you just deleted.

What you actually keep and lose

The last row is the one that decides most projects. On a conventional site, a marketer changes a layout. On a headless site, that is a front-end deployment.

REST or GraphQL

REST is in core and needs nothing installed. /wp-json/wp/v2/posts returns posts as JSON, with pagination and filtering, and it is already how the block editor talks to your site — the details are in the WordPress REST API.

Its weakness is over-fetching: you get the whole post object whether you wanted three fields or thirty, and assembling a page from posts plus menus plus options means several round trips.

GraphQL requires a plugin and lets the client ask for exactly the fields it needs, from several content types, in one query. That is a real advantage for a page composed of many pieces, at the cost of another dependency and a schema to maintain.

Start with REST. Move to GraphQL when you can point at the specific over-fetching that is hurting you.

What breaks, concretely

This is the section people skip and then rediscover in month three.

• SEO output. Your SEO plugin generates titles, meta descriptions, canonical tags, sitemaps and structured data into a front end that no longer exists. The front-end application has to produce all of it, and the sitemap needs a route of its own. Everything in the SEO checklist becomes your code's responsibility.
• Forms. A form plugin renders a form and processes a submission on the WordPress side. Headless, you build the form and post to an endpoint yourself, including spam handling.
• Preview. Editors expect to see a draft as it will appear. That requires deliberate work in the front-end app, and half-built implementations are why editors resent headless projects.
• Redirects. A redirect plugin acts on WordPress requests. Your front end never asks WordPress, so redirects have to move to the hosting layer or the app.
• Caching plugins do nothing useful — the layers are replaced by your own CDN and build cache.
• Comments, search and pagination are all now features you implement rather than features you have.

When it is justified

• The front end is genuinely an application, not a set of pages — heavy interactivity, real-time data, complex state.
• One content store feeds several destinations — a website, a mobile app, in-store screens. This is the strongest case by a distance.
• A front-end team already exists and works in a JavaScript framework daily.
• Output control is a hard requirement for performance or accessibility reasons that a theme cannot meet.
• WordPress is being kept for the editor while the rendering stack is being replaced for reasons of its own.

When it is not

• A marketing site a marketing team must run alone. They will need a developer for changes that used to take a minute.
• "For speed." Try caching, image optimisation and better hosting first; the method is in how to speed up a WordPress site. Most slow WordPress sites are slow for reasons headless does not address.
• "For security." It reduces the public attack surface and leaves the admin, the plugins and the database exactly where they were — the security checklist still applies in full.
• A small site with one developer, who has now doubled the number of applications to maintain.
• A team that will not staff the front end long term. A headless site nobody can deploy is worse than a conventional site nobody has updated.

Cheaper things to try first

Most of the reasons people want headless are addressable inside WordPress:

• A block theme gives you clean, controllable output — what is a WordPress block theme.
• Full-page caching plus a CDN gets you static-file delivery speeds without changing architecture.
• Removing the page builder often removes the bulk you were trying to escape — choosing a page builder.
• A custom block theme built for the design, rather than a heavy theme trimmed down.

If those get you where you need to be, you have avoided a permanent increase in operational complexity.

If you go ahead

• Model content properly first. Custom post types and taxonomies become your API schema; renaming them later breaks the front end.
• Lock down the WordPress side. It is now an API server: restrict the admin by IP where practical, keep two-factor authentication on every account, and do not expose more of the API than the front end needs.
• Decide preview early, not after the editors complain.
• Own the SEO output deliberately, with someone accountable for it.
• Keep the staging pair in sync — you now have two applications, and they can drift.

Headless is a reasonable architecture for the cases that need it. The failure mode is not technical; it is choosing it for a site whose real requirement was that non-developers could change it.