WordPress + Headless: WPGraphQL vs. REST, Caching Layers

WordPress is powerful. It runs over 40% of the web! But what if you don’t want to use it like a traditional CMS? That’s where headless WordPress comes into play. Instead of letting WordPress handle everything—including how your site looks—you connect it to a separate front-end, like React or Vue, and turn WordPress into a content brain.

This approach is great if you want lightning-fast websites, dynamic front-ends, or content shared across multiple platforms. But how do you connect the content from WordPress to your front-end app? That’s where API options like WPGraphQL and the native REST API come into play. And to make it fast, you’ll also need some smart caching.

What is Headless WordPress?

In a traditional WordPress site, WordPress handles both the back-end (where content is created) and the front-end (how it’s displayed). With headless, you just use WordPress for content management, and the front-end is handled by something else—usually a JavaScript framework.

Think of it this way: WordPress is the kitchen, and your front-end is the waiter delivering the food. You just need a way for the waiter to get the orders and serve them efficiently. That’s what APIs help with.

Meet the APIs: REST vs. WPGraphQL

REST API

REST is built into WordPress by default. It’s a standard system used by many platforms. You send HTTP requests like GET, POST, PUT, and it returns JSON responses.

Pros:

• Built-in to WordPress, no extra plugins required
• Familiar to many developers
• Works great for simple content delivery

Cons:

• Lots of endpoints needed for different data
• Over-fetching or under-fetching data is common
• Not optimized for complex or nested content

WPGraphQL

WPGraphQL is a plugin that adds a GraphQL API to your WordPress site. GraphQL lets the front-end ask for exactly the data it wants, nothing more, nothing less.

Pros:

• Only one endpoint needed: /graphql
• No over-fetching
• Easier to query complex and nested data
• Works beautifully with modern JS frameworks

Cons:

• You have to install and maintain a plugin
• Some learning curve if you’re new to GraphQL
• Larger plugins might degrade performance without caching

Which One Should You Use?

If your needs are simple—just fetching a few blog posts—a REST API might be fine. But if you’re building a dynamic site with lots of content relationships and custom fields, WPGraphQL is amazing.

Developers love it because they can write one query and get all the data needed in one go. No back-and-forth. No extra calls. Just clean JSON that fits your needs perfectly. Plus, WPGraphQL works great with popular front-end frameworks like Next.js and Gatsby.

But Wait, What About Performance?

Headless WordPress doesn’t magically make your site fast. In fact, without proper planning, it might slow things down! That’s why caching layers are super important.

Why Caching?

APIs take time. Each request pulls data from the database, builds a response, and sends it over the network. If you have 10 people visiting your homepage, that’s 10 API hits—unless you cache it.

Types of Caching

• Static Site Generation (SSG): Build pages at build time. Super fast, but not great for real-time content updates.
• Incremental Static Regeneration (ISR): Smart rebuilding of pages when content changes. Supported in Next.js.
• Server-side Caching: Store API responses in memory (e.g., Redis), so you don’t hit the database every time.
• Client-side Caching: Use tools like Apollo Client or SWR to store API responses in the user’s browser.

Where to Cache

This depends on your setup. If you’re using WPGraphQL with Apollo Client, you get built-in caching on the front-end. But for big sites, you may also need server-side caching or external tools like Cloudflare or Varnish.

Tips to Make It Blazing Fast

• Cache wisely: Use layers—browser, server, and edge
• Pre-fetch data: Use build-time queries if using SSG
• Use nodes wisely: In WPGraphQL, use specific node types like Post or Page to avoid bloated queries
• Use Fragments: GraphQL fragments reduce repeated query code and speed things up

Setting Up WPGraphQL

Getting started with WPGraphQL is easy:

1. Install the WPGraphQL plugin
2. Visit /graphql on your site
3. Start writing queries using a tool like GraphiQL Playground

If you’re using ACF (Advanced Custom Fields), the WPGraphQL ACF plugin lets you expose custom fields to your GraphQL queries. Magical!

Real Life Example

Let’s say you’re building a homepage in React. You want the latest 3 blog posts and the featured author name. Using REST, you might have to make multiple API calls: one for posts and one for author profile.

With GraphQL? One query and all your data is there. No extra fetches. No extra processing. Clean and easy.

{
  posts(first: 3) {
    nodes {
      title
      date
      author {
        node {
          name
        }
      }
    }
  }
}

Simple, right?

Common Pitfalls

• Overloading queries: Just because you can ask for everything doesn’t mean you should
• Skipping caching: Even fast queries can slow down if run for every user
• Security: Exposing too much data via API can be dangerous. Lock it down!

Bonus: Combining Both APIs

You don’t have to choose just one. Many developers use REST for simple data and GraphQL for complex ones. For example, use REST to fetch media assets and WPGraphQL for rich content pages. Totally valid!

Use the right tool for the job, and you’ll get the best of both worlds.

The Future of Headless WordPress

Headless setups are becoming more popular. Even tools like Gutenberg are working better with REST and GraphQL APIs. The community around WPGraphQL is growing fast, and more plugins are becoming API-ready out-of-the-box.

Final Thoughts

Headless WordPress is here to stay. If you want flexible front-ends, better performance, and personalized experiences, going headless is a great choice. Pair it up with WPGraphQL, sprinkle in some caching, and you’ve got a modern site that works hard behind the scenes without breaking a sweat.

So go ahead—behead your WordPress (gently) and set it free. Your dev life and site speed will thank you.