How to Use register_rest_route in WordPress for Custom REST API Endpoints

Use register_rest_route inside the rest_api_init action hook to create custom REST API endpoints in WordPress. It requires a namespace, route, and an array of arguments including HTTP methods and callback functions to handle requests.

Syntax

The register_rest_route function registers a new REST API route in WordPress. It takes three main parameters:

• Namespace: A string to group your routes, usually your plugin or theme name.
• Route: The specific path for your endpoint, starting with a slash.
• Args: An array defining HTTP methods, callback functions, permission checks, and argument validation.

php

register_rest_route( string $namespace, string $route, array $args = array() )

Example

This example shows how to create a simple REST API endpoint at /wp-json/myplugin/v1/hello that returns a greeting message.

php

<?php
add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/hello', array(
        'methods' => 'GET',
        'callback' => function () {
            return array('message' => 'Hello, WordPress REST API!');
        },
        'permission_callback' => '__return_true',
    ));
});

Output

{"message":"Hello, WordPress REST API!"}

Common Pitfalls

Common mistakes when using register_rest_route include:

• Not hooking into rest_api_init, so routes never register.
• Omitting permission_callback, which causes the endpoint to be inaccessible.
• Using incorrect HTTP methods or forgetting to specify them.
• Not returning valid data or not handling errors properly in the callback.

Always ensure your callback returns data in a format WordPress can convert to JSON.

php

<?php
// Wrong: Missing permission_callback
add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/bad', array(
        'methods' => 'GET',
        'callback' => function () {
            return 'No permission callback';
        },
    ));
});

// Right: Adding permission_callback
add_action('rest_api_init', function () {
    register_rest_route('myplugin/v1', '/good', array(
        'methods' => 'GET',
        'callback' => function () {
            return 'Has permission callback';
        },
        'permission_callback' => '__return_true',
    ));
});

Quick Reference

Parameter	Description	Example
namespace	Groups your routes, usually plugin or theme name	'myplugin/v1'
route	The endpoint path starting with a slash	'/hello'
methods	HTTP methods allowed (GET, POST, etc.)	'GET'
callback	Function to handle the request and return data	function() { return ['msg' => 'Hi']; }
permission_callback	Function to check if user can access endpoint	'__return_true' for public access

Key Takeaways

Always register custom REST routes inside the rest_api_init hook.

Specify HTTP methods and a permission_callback to make endpoints accessible.

Your callback must return data that can be converted to JSON.

Use namespaces and routes to organize your API endpoints clearly.

Test your endpoints with tools like Postman or browser to verify output.