Week 22: WordPress REST API & Headless WordPress

1. Built-in Endpoints

Every modern WordPress install exposes a REST API at /wp-json/ with zero extra setup — posts, pages, and any post type registered with show_in_rest => true (including Week 19's project CPT) are already reachable as JSON:

curl http://localhost:8000/wp-json/wp/v2/posts
curl http://localhost:8000/wp-json/wp/v2/posts/1
curl http://localhost:8000/wp-json/wp/v2/project        # your CPT, automatically
curl "http://localhost:8000/wp-json/wp/v2/posts?per_page=5&search=hello"

[
  {
    "id": 1,
    "title": { "rendered": "Hello from wp-cli" },
    "content": { "rendered": "<p>...</p>" },
    "excerpt": { "rendered": "<p>...</p>" },
    "date": "2026-01-15T10:00:00",
    "link": "http://localhost:8000/hello-from-wp-cli/"
  }
]

This is a genuinely different situation from Week 15's Laravel API — there, every route and response shape was deliberately built. Here, the API already exists the moment a post type opts in; the work shifts to shaping and securing it rather than building it from nothing.

2. Custom Endpoints

Custom data — like Week 21's inquiries table — needs a hand-registered route. register_rest_route() is WordPress's equivalent of Laravel's Route::get() from Week 9:

<?php

if (!defined('ABSPATH')) exit;

function pm_register_rest_routes() {
    register_rest_route('portfolio-manager/v1', '/projects/(?P<id>\d+)/inquiries', [
        'methods' => 'GET',
        'callback' => 'pm_get_inquiries_rest',
        'permission_callback' => 'pm_check_manage_options', // who's allowed to call this
        'args' => [
            'id' => ['validate_callback' => fn($value) => is_numeric($value)],
        ],
    ]);
}
add_action('rest_api_init', 'pm_register_rest_routes');

function pm_get_inquiries_rest(\WP_REST_Request $request): \WP_REST_Response {
    $projectId = (int) $request['id'];
    $inquiries = pm_get_inquiries_for_project($projectId); // from Week 21

    return new \WP_REST_Response($inquiries, 200);
}

function pm_check_manage_options(): bool {
    return current_user_can('manage_options');
}

portfolio-manager/v1 as the namespace is deliberate — the same versioning discipline from Week 15's Laravel API, applied here so a future breaking change can ship as v2 without touching existing integrations.

3. REST API Authentication

permission_callback from above is doing real work — without it (or with one that always returns true), the endpoint is open to anyone, including anonymous requests. current_user_can('manage_options') checks the currently logged-in WordPress user's capability, the same concept as Week 21's admin menu check.

For requests not coming from a logged-in browser session — a separate frontend app, a script — WordPress's REST API supports Application Passwords out of the box, no extra plugin required as of WordPress 5.6+:

wp user application-password create admin "headless-frontend"
# Prints a one-time password like: abcd 1234 efgh 5678

curl -u "admin:abcd1234efgh5678" \
  -X POST http://localhost:8000/wp-json/wp/v2/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "Created via REST API", "status": "publish"}'

4. Headless WordPress

Headless WordPress means using WordPress purely as a content backend — the admin, the database, the REST API — while an entirely separate application (a React/Next.js app, a static site generator) handles every bit of the actual frontend rendering:

async function getProjects() {
  const res = await fetch('http://localhost:8000/wp-json/wp/v2/project?_embed');
  const projects = await res.json();

  return projects.map(p => ({
    id: p.id,
    title: p.title.rendered,
    excerpt: p.excerpt.rendered,
    image: p._embedded?.['wp:featuredmedia']?.[0]?.source_url,
  }));
}

?_embed tells the REST API to include related resources (like the featured image) inline in the same response, avoiding a separate round-trip — the REST equivalent of Week 12's eager loading, solving the exact same N+1-shaped problem for API consumers.

In this architecture, everything built in Weeks 18–19 — the template hierarchy, The Loop, template parts — is entirely bypassed. WordPress never renders HTML at all; it's purely a data source and admin interface, with the REST API as the only boundary between the two halves.

5. When Headless Makes Sense

A genuine trade-off, not a strict upgrade — headless makes sense when:

• The frontend needs a framework WordPress themes can't provide (a native mobile app, a highly interactive SPA)
• Non-technical editors still need WordPress's mature admin UI for content management
• Frontend and backend teams want to work and deploy independently

And a traditional (non-headless) theme is usually the better call when:

• The site is primarily content — blog, brochure site, small business site — with no need for a separate app-like frontend
• SEO and fast first-paint matter and the team doesn't want to invest in server-side rendering for the separate frontend
• The team is smaller and maintaining two separate codebases (WordPress + frontend app) isn't worth the added complexity

Weeks 17–21 built the traditional path; this week added the option, not a replacement — most WordPress sites in production are still theme-rendered, and knowing both lets you pick deliberately rather than defaulting to whichever is trendier.

6. Hands-on Exercise

7. Knowledge Check

Four quick questions. Expand each to check your answer.