Как создать собственный REST API endpoint в WordPress: подробное руководство с примерами кода

Автор: Виктор Гусев | Опубликовано: 02.12.2025

WordPress имеет встроенный REST API, который позволяет взаимодействовать с сайтом через HTTP-запросы. Однако стандартных эндпоинтов не всегда хватает, особенно если нужно добавить специфическую логику или данные. В этой статье разберём, как создать собственный REST API endpoint в WordPress с примерами кода и полезными советами.

Что такое REST API endpoint в WordPress и зачем он нужен

REST API endpoint — это URL-адрес, по которому можно получить, создать, изменить или удалить данные на сайте через HTTP-запросы. WordPress из коробки предоставляет набор стандартных эндпоинтов для постов, пользователей, таксономий и других сущностей.

Но иногда нужно добавить кастомные данные или обработать логику, которая не входит в стандартный функционал. Например, выводить данные из пользовательских таблиц, фильтровать посты по дополнительным критериям или создавать кастомные действия.

Создание собственного REST API endpoint позволяет расширить возможности вашего сайта и интегрировать его с внешними сервисами или мобильными приложениями.

Регистрация собственного REST API endpoint в WordPress

Для создания своего endpoint нужно использовать хук rest_api_init и функцию register_rest_route. Рассмотрим базовый пример, который регистрирует маршрут /wpstuff/v1/message и возвращает простой ответ.

add_action('rest_api_init', 'wpstuff_register_custom_endpoint');
function wpstuff_register_custom_endpoint() {
    register_rest_route('wpstuff/v1', '/message', array(
        'methods' => 'GET',
        'callback' => 'wpstuff_handle_message_endpoint',
    ));
}

function wpstuff_handle_message_endpoint(WP_REST_Request $request) {
    return array('message' => 'Привет, это кастомный REST API endpoint от wpstuff.ru!');
}

Этот код добавляет новый GET-маршрут, который по адресу https://ваш-сайт/wp-json/wpstuff/v1/message возвращает JSON с сообщением. Очень просто, но уже рабочий пример.

Разбор параметров функции `register_rest_route`

Первый параметр — пространство имён (namespace), здесь wpstuff/v1. Это помогает группировать маршруты и версионировать API.

Второй параметр — путь эндпоинта после namespace, например /message.

Третий — массив опций, где указываем методы (GET, POST, PUT, DELETE) и callback — функцию, которая обрабатывает запрос и возвращает ответ.

Работа с параметрами запроса и валидация данных

Чаще всего нужно принимать параметры от клиента. Например, чтобы вернуть сообщение для конкретного пользователя. Добавим параметр name в наш endpoint.

add_action('rest_api_init', 'wpstuff_register_custom_endpoint');
function wpstuff_register_custom_endpoint() {
    register_rest_route('wpstuff/v1', '/message', array(
        'methods' => 'GET',
        'callback' => 'wpstuff_handle_message_endpoint',
        'args' => array(
            'name' => array(
                'required' => false,
                'validate_callback' => function($param, $request, $key) {
                    return is_string($param) && strlen($param) > 0;
                },
                'sanitize_callback' => 'sanitize_text_field',
            ),
        ),
    ));
}

function wpstuff_handle_message_endpoint(WP_REST_Request $request) {
    $name = $request->get_param('name');
    if ($name) {
        return array('message' => 'Привет, ' . $name . '! Это кастомный REST API endpoint.');
    } else {
        return array('message' => 'Привет! Это кастомный REST API endpoint.');
    }
}

Теперь, если сделать GET-запрос /wp-json/wpstuff/v1/message?name=Иван, сервер вернёт персонализированное приветствие. Валидация и очистка данных помогают защититься от некорректных или вредоносных значений.

Добавление POST-запроса и обработка данных

Часто API нужно не только читать данные, но и создавать или обновлять. Добавим POST-эндпоинт, который принимает JSON с сообщением и возвращает подтверждение.

add_action('rest_api_init', 'wpstuff_register_post_endpoint');
function wpstuff_register_post_endpoint() {
    register_rest_route('wpstuff/v1', '/send-message', array(
        'methods' => 'POST',
        'callback' => 'wpstuff_handle_post_message',
        'args' => array(
            'message' => array(
                'required' => true,
                'validate_callback' => function($param) {
                    return is_string($param) && strlen($param) > 0;
                },
                'sanitize_callback' => 'sanitize_textarea_field',
            ),
        ),
        'permission_callback' => function() {
            return current_user_can('edit_posts'); // пример проверки прав
        }
    ));
}

function wpstuff_handle_post_message(WP_REST_Request $request) {
    $message = $request->get_param('message');
    // Здесь можно сохранить сообщение в базу или отправить куда-то
    return array('status' => 'success', 'received_message' => $message);
}

Обратите внимание на permission_callback — это функция, проверяющая, имеет ли текущий пользователь право выполнять запрос. Это важно для безопасности.

Примеры полезных плагинов для расширения REST API в WordPress

Иногда нет смысла писать всё с нуля, можно воспользоваться готовыми решениями:

WP REST API Controller — позволяет управлять доступом и полями для стандартных эндпоинтов без программирования.
Advanced Custom Fields to REST API — добавляет поля ACF в стандартные REST API ответы.
WPGraphQL — альтернативный API, использующий GraphQL вместо REST, для гибких запросов.

Но если нужны уникальные сценарии, самописные endpoint будут незаменимы.

Отладка и тестирование собственного REST API

Для тестирования можно использовать инструменты:

Postman — мощный клиент для HTTP-запросов с удобным интерфейсом.
curl — командная строка для отправки запросов.
Встроенный в браузер REST API explorer WordPress — обычно доступен по /wp-json/.

Важно проверять корректность ответов, коды статуса HTTP и обработку ошибок.

Обработка ошибок и возвращение статусов HTTP

Для корректной работы API нужно возвращать правильные коды ошибок. В WordPress для этого используют класс WP_Error. Пример возврата ошибки:

function wpstuff_handle_message_endpoint(WP_REST_Request $request) {
    $name = $request->get_param('name');
    if (!$name) {
        return new WP_Error('no_name', 'Параметр name обязателен', array('status' => 400));
    }
    return array('message' => 'Привет, ' . $name . '!');
}

Клиент получит ответ с HTTP 400 и сообщением об ошибке.

Заключение

Создание собственного REST API endpoint в WordPress — мощный способ расширить функционал сайта и интегрироваться с внешними сервисами. Важно правильно регистрировать маршруты, валидировать и очищать входящие данные, а также защищать эндпоинты проверкой прав. Практика и тестирование помогут создать надёжный и удобный API.

Как создать собственный REST API endpoint в WordPress