5.5REST API & headless WordPress (concepts)
The essentials in 30 seconds
- The REST API exposes WordPress content as JSON: /wp-json/wp/v2/posts already returns posts.
- Headless uses WordPress as a content back end, with a separate front end (React, Next.js, mobile app).
- Benefits: front-end freedom and multi-channel distribution; trade-offs: complexity, loss of preview and of many front-end plugins.
Running mini-case — should the workshop go headless?
A developer suggests a "more modern" headless site to Hassan. Samir examines the real need: a showcase site and a small shop, with no mobile app or multi-channel requirement. He concludes that classic WordPress remains simpler and cheaper. He nonetheless shows Hassan the REST API to illustrate the possible opening towards a guided-tour app, without committing to a rebuild.
Sequel to case 5.4 — know the possibilities without overselling.
1. The REST API in practice
WordPress includes a REST API: an interface that exposes content and some actions as JSON, a format other applications can read. Opening /wp-json/wp/v2/posts on a site already returns the list of posts. It is the same technology that powers the block editor and many integrations.
This API lets an external application — front-end site, mobile app, dashboard — read or publish content. Samir can use it to connect a tool without rebuilding the site. He checks which endpoints are public and which require authentication.
2. Headless: promise and trade-offs
Headless WordPress separates the content back end from the front end that displays it. WordPress is kept to manage posts and media, and display happens through React, Next.js or a mobile app. Benefits: total front-end freedom, possible performance gains, distribution of the same content across several channels.
The trade-offs are real: two skill sets are needed (WordPress + front end), and you must handle preview, forms, SEO, caching and the plugins that depend on the front end. For most sites, classic WordPress remains simpler and cheaper. Headless is justified for projects with a genuine multi-channel need or a technical team.
🔎 Concrete example — A guided-tour application (Samir's case)
Real need: a mobile app for touring the workshop.
WordPress remains the content back end.
REST API: /wp-json/wp/v2/realisations.
Application: reads the entries as JSON.
Classic showcase site kept for the web.
→ No headless rebuild of the whole site.Result: a targeted use of the API, without a costly rebuild.
Lesson: the architecture is chosen according to the need.
Section vocabulary
- REST API
- An interface that exposes WordPress content and actions as JSON.
Simple example: /wp-json/wp/v2/posts.
What it is not: believing it is reserved for developers.
Reflex: API = the data's front door.
- JSON
- A lightweight data format that applications can read.
Simple example: the API response lists the posts.
What it is not: confusing JSON and HTML.
Reflex: JSON = structured data.
- Headless
- An architecture where WordPress provides the content and a separate front end displays it.
Simple example: a React front end on the WordPress API.
What it is not: believing headless is always faster.
Reflex: headless = back end and front end separated.
- Endpoint
- The precise API address that returns a resource.
Simple example: the projects endpoint.
What it is not: exposing sensitive data without control.
Reflex: check permissions and visibility.
- API authentication
- A mechanism that protects non-public endpoints.
Simple example: an application key to publish.
What it is not: leaving writing open to everyone.
Reflex: sensitive actions require auth.
In practice — Exploring the API without a rebuild
- Open /wp-json/wp/v2/posts on a test site and observe the JSON response.
- Find a useful endpoint and check whether it is public or protected.
- Note what a separate front end would have to handle: preview, forms, SEO, caching.
- Compare with a classic site and decide what is genuinely justified.
Ready-to-use script — reframing headless (25s)
"Headless is powerful for a mobile app or multiple channels, but it doubles the complexity and the cost. For your showcase site and your shop, classic WordPress remains simpler. We can use the API for a specific purpose without rebuilding everything."
Talk about the need before the technology: that is the role of advice.
Copy-paste template — headless decision
GENUINE MULTI-CHANNEL NEED: yes / no
MOBILE APP PLANNED: yes / no
FRONT-END TEAM AVAILABLE: yes / no
PREVIEW / FORMS / SEO TO RETHINK: _______________
PUBLIC ENDPOINTS CHECKED: yes / no
DECISION: classic WordPress / headless / targeted APIShowcase site
Classic WordPress; API only for an integration.
Mobile app
REST API + mobile front end, WordPress back end.
Multi-channel
One content, several front ends: web, app, kiosks.
Technical team
Headless with a React/Next.js front end and CI/CD.
✓ Best practices
- Start from the need before choosing the architecture.
- Check which endpoints are public.
- Protect writing with authentication.
✗ Common pitfalls
- Choosing headless out of fashion.
- Leaving the API open without control.
- Forgetting preview, forms and SEO in the separate front end.
Key takeaways
- The REST API exposes WordPress content as JSON.
- Headless separates the content back end from the front end.
- Benefits of freedom, trade-offs of complexity.
- Endpoint security is essential.
48h Challenge — apply tomorrow
Open a test site's API, find a public endpoint and a protected endpoint, then list what a headless front end would have to handle. 25 minutes.
- I understand what the REST API exposes.
- I can explain headless and its trade-offs.
- I check endpoint security.
Frequently asked questions
Is headless the future of WordPress?
It is a path suited to certain projects — high traffic, custom front end, multi-channel, technical team — not a general necessity. For most sites, classic WordPress remains simpler, cheaper and performant with caching.
Do I need to know how to program to do headless?
Yes, significantly more than for classic WordPress: the separate front end requires web developer skills. This section is an introduction to the concepts, to know when it is worth it, not an implementation tutorial.
Is the REST API accessible to everyone?
Some read endpoints are public, others require authentication. Write actions must be protected. You must check the configuration and never expose sensitive data.
What is "headless" WordPress?