The WordPress REST API turned WordPress from a website builder into a content platform. Every post, page, category and media file is available as JSON at a predictable address, which means any front end can use WordPress as its content source. That’s “headless WordPress”, and it’s exactly how the blog you’re reading works: posts are written in WordPress and displayed by a Next.js site.

This is what we’ve learned running it in production.

How the REST API works

WordPress exposes its content under /wp-json/wp/v2/. For example:

GET /wp-json/wp/v2/posts?per_page=10&_embed
GET /wp-json/wp/v2/posts?slug=my-post-slug
GET /wp-json/wp/v2/categories

Two parameters save a lot of work:

• _embed includes the featured image, author and categories in the same response, instead of separate requests for each
• _fields returns only the fields you ask for, which keeps responses small, such as _fields=slug,date for a sitemap

Public content needs no authentication. Drafts, previews and anything that writes to WordPress need an application password, created per user in their profile, so an integration never uses someone’s real login.

REST API or WPGraphQL?

The REST API is built in and good enough for most sites. WPGraphQL, a popular plugin, lets the front end request exactly the fields it needs in one query, which helps on complex sites with lots of related content. For a blog or marketing site, we start with REST.

The parts that need planning

Caching and freshness

Fetching from WordPress on every page view would be slow. Instead, the front end builds pages ahead of time and refreshes them periodically, and WordPress can send a webhook on publish so an updated post appears within seconds. Plan this from day one, including what happens when WordPress is briefly unavailable.

Previews

Editors expect a “Preview” button that works. In a headless setup it has to be built: the front end needs an authenticated route that fetches the draft version. It’s straightforward, but easy to forget until an editor asks.

SEO data

SEO plugins such as Yoast add their title, description and social data to the REST API responses. The front end has to read and output them, along with a sitemap, canonical URLs and structured data.

Images

Editors upload large originals. The front end should resize and convert them to modern formats, using its framework’s image optimization, so a 3 MB upload doesn’t reach a phone.

Plugins that stop working

Anything that changes the front end, such as page builders, form plugins, sliders or cookie banners, won’t appear on a headless site. Those features have to be rebuilt in the front end or replaced with services. Check your plugin list before committing.

Is headless WordPress right for you?

It’s a good fit when your team already knows WordPress and you want a faster, more flexible front end, or the same content in several places. It’s more than you need if a standard WordPress theme would do the job, since you’ll be maintaining two systems instead of one.

We build headless sites on WordPress and on dedicated headless platforms like Sanity and Contentful. See our headless CMS development service, or our comparison of WordPress, headless and custom builds.