How does WordPress become "headless"?

WordPress has natively included a REST API since version 4.7 (December 2016). This API exposes content (posts, pages, taxonomies, media) as JSON endpoints accessible by any HTTP client. No additional installation is needed: any WordPress instance running version 4.7 or later can operate in headless mode.

The REST API works with the standard HTTP protocol:

  • The frontend sends a GET request to an endpoint (for example /wp-json/wp/v2/posts)
  • WordPress returns the data in JSON format
  • The frontend parses the JSON and generates the corresponding HTML

An alternative to the REST API is WPGraphQL, a plugin that adds a GraphQL endpoint. GraphQL lets the frontend specify exactly which fields it needs, reducing the amount of data transferred.

The Gutenberg editor: a content structure suited to headless

WordPress's block editor (Gutenberg, integrated since WordPress 5.0) breaks content down into semantic blocks. This structure is particularly well-suited to a headless architecture.

Before Gutenberg:

Article = a single monolithic HTML field

With Gutenberg:

Article = [Heading block] + [Image block] + [Paragraph block] + [List block] + [Quote block]

The advantages of this structure for headless:

  • Each block is a JSON object with a type and attributes, which lets the frontend render it with its own components
  • Content is reusable: the same block can be displayed differently depending on context (website, mobile app, newsletter)
  • Consistency is guaranteed because the structure is enforced by the block schema

What changes depending on your role

For content editors

For editors: the admin interface stays the same

The WordPress back-office doesn't change in headless mode. Creating posts, managing media, and the publication workflow stay identical. The headless decoupling happens exclusively on the server side and the client side, with no impact on the admin interface.

What stays the same:

  • WordPress admin interface unchanged
  • Post and page creation via Gutenberg
  • Media library management (upload, edit, organize)
  • Publication workflow (draft, review, publish)

What improves:

  • Content can be consumed by multiple clients (website, mobile app, interactive kiosk)
  • Preview can take place on the actual frontend rendering
  • Publication times are optimized because the backend no longer has to generate the public HTML

For site visitors

Traditional WordPress:

  • Loading: 3 to 5 seconds (the PHP server generates the HTML on every request)
  • Design: constrained by the theme system and PHP templates
  • Experience: full page reload on every navigation

Headless WordPress:

  • Loading: under 1 second (HTML pre-generated via SSG or optimized server rendering via SSR)
  • Design: no theme constraints, the frontend is fully custom
  • Experience: smooth navigation with no full reload (client-side routing)

A step-by-step workflow example

Situation: publishing a new article "10 gardening tips"

What headless brings to the workflow

The extra step in the headless process (the frontend consuming the API) is what enables a high-performance site with a fully custom design. This decoupling layer (backend/frontend separation) is the source of performance and flexibility gains.

Traditional WordPress:

  1. The author publishes the article in WordPress
  2. WordPress generates the HTML via the active PHP theme
  3. The visitor receives this PHP-generated page

Headless WordPress:

Authoring in WordPress

The author creates the article in the WordPress back-office. The interface and workflow are identical to traditional mode.

Exposure via the API

WordPress stores the content in the database and exposes it automatically via the REST API (or GraphQL). This step requires no manual intervention.

Consumption by the frontend

The frontend application (Next.js, Nuxt.js, Gatsby) sends a request to the API, receives the JSON, and generates the HTML using its own components and styles.

Visitor-side rendering

The visitor receives an optimized page: pre-generated HTML or server rendering, with client-side navigation, optimized images, and reduced load time.

  1. The author publishes the article in WordPress (identical)
  2. WordPress exposes the content via the REST API or GraphQL
  3. The frontend consumes the API and generates the HTML with its own components
  4. The visitor receives an optimized page with smooth navigation and fast loading

Plugins and features

What works without modification:

  • Content management plugins (ACF, forms, galleries)
  • SEO plugins (Yoast SEO, Rank Math) — metadata is exposed via the API
  • User and role management
  • Backend backup and security plugins

What is replaced or adapted:

  • WordPress themes are no longer used (rendering is handled by the frontend)
  • Server-side WordPress caching is replaced by CDN caching and static pre-rendering
  • Some plugins that inject HTML into the frontend (sliders, popups) must be replaced with native frontend components

Frequently asked questions

"Is the migration complex?" For editors, there is no migration: the interface stays the same. The complexity lies in frontend development, which is a full-fledged web development project.

"Is preview possible?" Yes. Next.js offers a "Preview" mode that lets you view a draft on the actual frontend rendering. Other frameworks provide equivalent mechanisms.

"Is existing content compatible?" All existing content is accessible via the REST API. Posts, pages, media, and taxonomies are exposed without modification.

"Can we revert?" Yes. WordPress remains intact. Simply reactivate a theme to return to traditional operation. The content is unaffected by headless mode.