Как использовать REST API в WordPress для создания нестандартных эндпоинтов

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

Что такое REST API в WordPress и зачем нужны нестандартные эндпоинты

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

Стандартные эндпоинты покрывают большинство базовых нужд, но иногда требуется создать собственные маршруты для специфических операций: например, получить данные из нестандартных таблиц, реализовать бизнес-логику, обеспечить доступ к кастомным данным или интегрироваться с внешними системами.

Создание нестандартных эндпоинтов позволяет:

Возвращать кастомные данные, которых нет в стандартных API.
Добавлять собственные методы обработки запросов (GET, POST, PUT, DELETE).
Реализовывать сложную бизнес-логику и валидацию данных.
Управлять доступом и правами на уровне API.
Интегрировать WordPress с мобильными приложениями, SPA или внешними сервисами.

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

Для создания нового эндпоинта нужно использовать функцию register_rest_route(), которая регистрирует маршрут в REST API. Обычно это делается в хуке rest_api_init.

Рассмотрим пример создания простого эндпоинта /wp-json/wptips/v1/message, который возвращает приветственное сообщение.

add_action('rest_api_init', 'wptips_register_custom_endpoint');
function wptips_register_custom_endpoint() {
    register_rest_route('wptips/v1', '/message', array(
        'methods' => 'GET',
        'callback' => 'wptips_get_message',
        'permission_callback' => '__return_true' // доступ открыт всем
    ));
}

function wptips_get_message(WP_REST_Request $request) {
    return new WP_REST_Response(array(
        'message' => 'Привет от WP Tips! Ваш кастомный REST API работает.'
    ), 200);
}

Объяснение:

rest_api_init — хук для инициализации REST API.
register_rest_route — регистрирует маршрут. Первый параметр — пространство имён и версия (wptips/v1), второй — путь (/message).
methods — HTTP метод (GET).
callback — функция-обработчик запроса.
permission_callback — проверка доступа, здесь разрешено всем.
wptips_get_message — возвращает ответ с сообщением в формате JSON.

Как передавать параметры и обрабатывать POST-запросы

Часто нужно получать данные от клиента, например, через POST-запрос. В REST API параметры можно передавать в теле запроса или URL.

Создадим эндпоинт /wp-json/wptips/v1/sum, который принимает два числа и возвращает их сумму.

add_action('rest_api_init', 'wptips_register_sum_endpoint');
function wptips_register_sum_endpoint() {
    register_rest_route('wptips/v1', '/sum', array(
        'methods' => 'POST',
        'callback' => 'wptips_calculate_sum',
        'permission_callback' => '__return_true'
    ));
}

function wptips_calculate_sum(WP_REST_Request $request) {
    $params = $request->get_json_params();
    $a = isset($params['a']) ? (int)$params['a'] : 0;
    $b = isset($params['b']) ? (int)$params['b'] : 0;
    return array('sum' => $a + $b);
}

Пояснения:

get_json_params() — получает параметры из JSON тела запроса.
Параметры a и b преобразуются в целые числа.
Возвращается массив с суммой чисел.

Реализация проверки прав доступа к эндпоинтам

Очень важно контролировать, кто может обращаться к вашим кастомным эндпоинтам. Для этого используется параметр permission_callback. Рассмотрим пример, где доступ имеют только авторизованные пользователи с ролью администратора.

add_action('rest_api_init', 'wptips_register_private_endpoint');
function wptips_register_private_endpoint() {
    register_rest_route('wptips/v1', '/admin-data', array(
        'methods' => 'GET',
        'callback' => 'wptips_get_admin_data',
        'permission_callback' => 'wptips_check_admin_permission'
    ));
}

function wptips_check_admin_permission() {
    return current_user_can('administrator');
}

function wptips_get_admin_data() {
    return array('secret' => 'Это данные только для администраторов');
}

Обратите внимание, что если пользователь не авторизован или не имеет нужных прав, сервер вернёт ошибку 403.

Пример: Получение кастомных записей через REST API

Предположим, у вас есть кастомный тип записи book и вы хотите добавить эндпоинт, который возвращает книги с определённым метаполем.

Пример регистрации кастомного эндпоинта с фильтрацией:

add_action('rest_api_init', 'wptips_register_books_endpoint');
function wptips_register_books_endpoint() {
    register_rest_route('wptips/v1', '/books', array(
        'methods' => 'GET',
        'callback' => 'wptips_get_books_by_meta',
        'permission_callback' => '__return_true',
        'args' => array(
            'genre' => array(
                'required' => false,
                'validate_callback' => 'rest_validate_request_arg',
            ),
        ),
    ));
}

function wptips_get_books_by_meta(WP_REST_Request $request) {
    $genre = $request->get_param('genre');

    $args = array(
        'post_type' => 'book',
        'posts_per_page' => 10,
    );

    if ($genre) {
        $args['meta_query'] = array(
            array(
                'key' => 'genre',
                'value' => $genre,
                'compare' => '=',
            ),
        );
    }

    $query = new WP_Query($args);
    $books = array();
    while ($query->have_posts()) {
        $query->the_post();
        $books[] = array(
            'id' => get_the_ID(),
            'title' => get_the_title(),
            'genre' => get_post_meta(get_the_ID(), 'genre', true),
        );
    }
    wp_reset_postdata();

    return $books;
}

Такой эндпоинт позволяет получить книги по жанру, если указать параметр ?genre=фантастика.

Полезные плагины для работы с REST API в WordPress

Хотя создание кастомных эндпоинтов вручную гибко и эффективно, существуют плагины, которые облегчают работу с REST API:

WP REST API Controller — позволяет настраивать и отключать эндпоинты без кода.
Advanced Custom Fields (ACF) с дополнением ACF to REST API — добавляет данные ACF в стандартные REST эндпоинты.
JWT Authentication for WP REST API — реализует авторизацию через JWT для безопасного доступа к API.

Использование этих плагинов совместно с собственными эндпоинтами расширит возможности вашего API и упростит разработку.

Практические советы и рекомендации

При работе с кастомными REST API эндпоинтами в WordPress стоит учесть несколько важных моментов:

Безопасность: всегда проверяйте права доступа через permission_callback, особенно если эндпоинт изменяет данные.
Валидация данных: используйте args с validate_callback для проверки входящих параметров.
Формат ответа: возвращайте объекты WP_REST_Response для гибкого управления статусом и заголовками.
Кэширование: при необходимости реализуйте кэширование ответов для снижения нагрузки.
Документация: поддерживайте документацию к API для удобства использования другими разработчиками.