ThisCalculator

Everyday

Headless WordPress with Next.js: When Is the API Enough?

Updated · Standard formula, shown below

Yes, the WordPress REST API is often enough for a headless WordPress + Next.js site, but not always. You should choose the API-only approach when your content is mostly text, images, and standard post types, and you don’t need real-time updates, complex queries, or heavy WooCommerce integration. If you need those, you’ll want to add WPGraphQL or a middleware layer.

Background: Why Go Headless at All?

Traditional WordPress renders HTML on the server and sends it to the browser. A headless setup decouples the backend (WordPress) from the frontend (Next.js). The frontend fetches content via an API and renders it itself, often as static pages or server-rendered pages. This gives you better performance, a modern React-based development experience, and a clearer separation between content editing and presentation.

Next.js is a popular choice because it supports static site generation (SSG), server-side rendering (SSR), and incremental static regeneration (ISR). With SSG, pages are built at deploy time, which is fast for readers. With ISR, you can revalidate pages in the background after a set time, so content updates without a full rebuild.

How the WordPress REST API Works with Next.js

WordPress exposes content through the REST API at /wp-json/wp/v2/. You can fetch posts, pages, media, categories, tags, and custom post types using simple HTTP requests. In Next.js, you typically fetch this data in getStaticProps or getServerSideProps.

For example, to get the latest 10 posts:

const res = await fetch('https://example.com/wp-json/wp/v2/posts?per_page=10');
const posts = await res.json();

You can then pass posts to your page component. This is simple, but there are limitations. The REST API returns a lot of data you don’t need, and it doesn’t allow complex queries like “posts in category X with meta value Y and sorted by custom field Z” without multiple requests. It also doesn’t support GraphQL-style queries where you ask for exactly the fields you want.

When the REST API Is Enough

The REST API is sufficient for many common scenarios:

  • Content-heavy blogs and news sites – you just need posts, pages, and media.
  • Marketing sites – a few pages, maybe a contact form, and a blog.
  • Portfolio sites – projects and images.
  • Documentation sites – structured content with headings and code blocks.
  • Sites with low update frequency – you can use SSG and rebuild when content changes.

If your content editors only use the standard post editor, and you don’t need real-time updates, the REST API is fine. You can even use the _embed parameter to get featured images and author info in one request.

When the REST API Is Not Enough

There are clear signs you need something more:

  • Complex queries – you need to combine multiple filters, sort by custom fields, or search across post types. The REST API can’t do this efficiently.
  • WooCommerce – the WooCommerce REST API works, but it’s slow and limited for building custom storefronts. WPGraphQL with the WooGraphQL plugin is a better choice.
  • Real-time updates – if you need to reflect content changes instantly (e.g., a news site with breaking stories), you’ll need webhooks or a service like Next.js ISR with on-demand revalidation.
  • Performance – the REST API returns large JSON responses. If you have many posts or heavy traffic, this can slow down your builds and increase bandwidth.
  • Custom fields and ACF – the REST API exposes ACF fields, but only if you register them. WPGraphQL makes this much easier and more flexible.

WPGraphQL vs. REST API

WPGraphQL is a free plugin that adds a GraphQL endpoint to WordPress. GraphQL lets you request exactly the data you need, in one request. For example, you can get a post with its featured image, author, and custom fields like this:

query Post($id: ID!) {
  post(id: $id) {
    title
    content
    featuredImage { node { sourceUrl } }
    author { node { name } }
    customField
  }
}

This is cleaner and more efficient than REST. WPGraphQL also supports complex queries with filters and pagination. The tradeoff is that you need to install and maintain another plugin, and you need to learn GraphQL if you don’t know it already.

For most new headless projects, WPGraphQL is the recommended choice. The REST API is fine for simple sites, but WPGraphQL scales better and is more pleasant to work with.

How to Choose: A Decision Framework

Here’s a simple way to decide:

  1. List your content types – posts, pages, custom post types. If you only have a few, REST is fine.
  2. List your queries – how do you need to filter and sort? If you need anything beyond basic category/tag filters, consider WPGraphQL.
  3. Check your update frequency – if you update content often and need it live quickly, use ISR with on-demand revalidation. This works with both REST and GraphQL.
  4. Consider your team – if you’re comfortable with GraphQL, use it. If not, REST is easier to start with.
  5. Test performance – build a prototype with both and measure build time and page load.

You can also use a hybrid: use REST for simple pages and WPGraphQL for complex ones. But that adds complexity, so it’s better to pick one.

Common Problems and Misconceptions

One common misconception is that headless WordPress is always faster. It can be, but not automatically. If you use SSR on every request, you’re just moving the rendering from WordPress to Next.js. The real speed gain comes from SSG and caching. Make sure you use SSG for content that doesn’t change often.

Another issue is previews. In a traditional WordPress site, the preview button shows a draft. In headless, you need to implement previews using the WordPress preview API and Next.js preview mode. It’s doable, but it requires extra work.

Also, be careful with the REST API’s content field. It returns HTML that may contain inline styles or scripts. You need to sanitize it to prevent XSS attacks. The same applies to any user-generated content.

Finally, don’t forget about SEO. Next.js handles meta tags well, but you need to ensure that your page URLs match your WordPress permalinks, or set up redirects. Also, generate a sitemap using Next.js or a plugin.

Costs and Maintenance

Headless WordPress doesn’t cost more in terms of hosting – you still need a WordPress host and a Node.js host (like Vercel or Netlify). But you have more moving parts: two deployments, API connections, and more code to maintain. You’ll also need to handle authentication if you have private content.

If you use WPGraphQL, you need to keep the plugin updated. If you use custom endpoints, you need to maintain them. Overall, the maintenance burden is higher than a traditional WordPress site, but the performance and flexibility can be worth it.

Alternatives to Headless WordPress

If you’re not sure about headless, consider these alternatives:

  • Traditional WordPress with a caching plugin – often fast enough for most sites, and much simpler.
  • Next.js with a headless CMS like Contentful or Sanity – these are built for headless from the start, with better APIs and previews.
  • Static site generators like Eleventy or Astro – if you don’t need a CMS, these are lighter.

WordPress is a great choice if you need a familiar editing experience and lots of plugins. But if you’re building a complex, high-traffic site, a dedicated headless CMS might be easier.

Frequently Asked Questions

Can I use the REST API with Next.js ISR? Yes, you can fetch data in getStaticProps with a revalidate time. The page will be regenerated in the background at that interval. For on-demand revalidation, you can call the Next.js API route from a WordPress webhook when content is updated.

Is WPGraphQL faster than the REST API? Generally yes, because it returns only the data you ask for, reducing payload size. It also allows more efficient queries. However, the actual speed depends on your server and the complexity of the query.

Do I need to use a plugin for the REST API? No, the REST API is built into WordPress. You just need to enable pretty permalinks. For WPGraphQL, you need to install the plugin.

How do I handle WordPress authentication in headless? For public content, you don’t need auth. For private content, you can use JWT authentication (a plugin) or OAuth. For admin previews, use the built-in preview mechanism with a nonce.

Can I use Next.js with WordPress for e-commerce? Yes, but it’s complex. WooCommerce has a REST API, but it’s not ideal for building a custom storefront. You might want to use WPGraphQL with WooGraphQL, or consider a dedicated e-commerce platform like Shopify.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.