WordPress REST API

The WordPress REST API allows applications to interact with a WordPress site using JSON over HTTP. It exposes WordPress data (posts, pages, users, taxonomies, custom post types) through RESTful endpoints.

It powers the WordPress Block Editor and enables headless architectures, custom dashboards, mobile apps, and external integrations.

What Is REST?

API – A set of rules that allows systems to communicate.

REST (Representational State Transfer) – A standard for structuring APIs using:

  • Resources (posts, users)

  • Routes (URLs)

  • HTTP methods (GET, POST, PUT, DELETE)

  • JSON responses

Example of another API: Google Maps API.

Default REST Endpoints

Base URL:

https://example.com/wp-json/

Examples:

GET /wp-json/wp/v2/posts
GET /wp-json/wp/v2/pages
GET /wp-json/wp/v2/users
GET /wp-json/wp/v2/categories

Custom post types (if show_in_rest => true):

GET /wp-json/wp/v2/{cpt-slug}

Core REST API Concepts

Routes & Endpoints
A route is a URI. An endpoint is a route + HTTP method.

Requests
Handled using WP_REST_Request.

Responses
Returned using WP_REST_Response.

Schema
Defines structure, validation, and data types.

Controller Classes
Manage routes, permissions, schema, and responses.

Creating a Custom Route (Plugin Example)

add_action('rest_api_init', function () {

    register_rest_route('myplugin/v1', '/hello', [
        'methods'  => 'GET',
        'callback' => 'my_custom_callback',
        'permission_callback' => '__return_true',
    ]);

});

function my_custom_callback() {
    return [
        'message' => 'Hello from Custom REST API'
    ];
}

Access:

/wp-json/myplugin/v1/hello

Route with Parameters

register_rest_route('myplugin/v1', '/post/(?P<id>\d+)', [
    'methods'  => 'GET',
    'callback' => 'get_post_by_id',
    'permission_callback' => '__return_true',
]);

function get_post_by_id($request) {

    $post = get_post($request['id']);

    if (!$post) {
        return new WP_Error('no_post', 'Invalid ID', ['status' => 404]);
    }

    return $post;
}

Custom Post Type Endpoint with Pagination

register_rest_route('myplugin/v1', '/rt-celebs', [
    'methods'  => 'GET',
    'callback' => 'get_rt_celebs',
    'permission_callback' => '__return_true',
]);

function get_rt_celebs($request) {

    $page = $request->get_param('page') ?: 1;

    $query = new WP_Query([
        'post_type'      => 'rt-celebs',
        'posts_per_page' => 5,
        'paged'          => $page,
    ]);

    return [
        'total_posts'  => $query->found_posts,
        'total_pages'  => $query->max_num_pages,
        'current_page' => $page,
        'data'         => $query->posts,
    ];
}

Authentication Options

  • Cookie authentication (logged-in users)

  • Application Passwords (recommended for external apps)

  • Basic Auth (development only)

  • JWT / OAuth (advanced setups)

Example using cURL:

curl --user username:password https://example.com/wp-json/wp/v2/posts

Restricting REST API (CORS Example)

add_action('rest_api_init', function() {

    remove_filter('rest_pre_serve_request', 'rest_send_cors_headers');

    add_filter('rest_pre_serve_request', function($value) {
        header('Access-Control-Allow-Origin: https://allowed-domain.com');
        header('Access-Control-Allow-Methods: GET, POST');
        return $value;
    });

});

WP-CLI Scaffold Command

wp scaffold plugin my-plugin

Generates plugin boilerplate structure.

Other examples:

wp scaffold post-type movie
wp scaffold taxonomy genre

JavaScript Example

fetch('/wp-json/wp/v2/posts')
  .then(res => res.json())
  .then(data => console.log(data));

The WordPress REST API exposes site data as JSON, follows REST standards, supports authentication, and enables modern WordPress development including headless implementations and custom administrative interfaces.