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

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

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

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

Кастомные эндпоинты позволяют:

Предоставлять данные в нужном формате и структуре
Обрабатывать специфичные запросы (например, фильтры, сортировки, авторизацию)
Интегрировать WordPress с мобильными приложениями, SPA или внешними сервисами
Создавать собственные бизнес-логики на уровне API

Без знания, как создавать такие эндпоинты, вы ограничены стандартными возможностями и не сможете гибко управлять данными сайта.

Создание базового кастомного эндпоинта в WordPress

Для создания кастомного эндпоинта в WordPress используется функция register_rest_route(), которую нужно вызывать на хуке rest_api_init. Ниже пример простого эндпоинта, который возвращает приветственное сообщение.

add_action('rest_api_init', function () {
    register_rest_route('wptest/v1', '/hello', array(
        'methods' => 'GET',
        'callback' => 'wptest_hello_endpoint',
    ));
});

function wptest_hello_endpoint(WP_REST_Request $request) {
    return new WP_REST_Response(array(
        'message' => 'Привет от WPTest REST API!'
    ), 200);
}

Объяснение:

'wptest/v1' — пространство имён и версия API
'/hello' — маршрут (endpoint)
'methods' => 'GET' — HTTP метод, который поддерживается
'callback' — функция, которая обрабатывает запрос

Теперь, перейдя по URL https://ваш-сайт.ru/wp-json/wptest/v1/hello, вы получите JSON с сообщением.

Добавление параметров и обработка запросов

Часто требуется принимать параметры в запросе для фильтрации данных. Рассмотрим пример эндпоинта, который принимает параметр name и возвращает приветствие с этим именем.

add_action('rest_api_init', function () {
    register_rest_route('wptest/v1', '/greet', array(
        'methods' => 'GET',
        'callback' => 'wptest_greet_endpoint',
        'args' => array(
            'name' => array(
                'required' => true,
                'validate_callback' => function($param, $request, $key) {
                    return is_string($param) && !empty($param);
                },
            ),
        ),
    ));
});

function wptest_greet_endpoint(WP_REST_Request $request) {
    $name = sanitize_text_field($request->get_param('name'));
    return new WP_REST_Response(array(
        'message' => "Привет, $name! Добро пожаловать в WPTest API."
    ), 200);
}

Здесь мы добавили проверку обязательного параметра и валидацию. Если параметр не передан или невалидный, WordPress автоматически вернёт ошибку.

Пример: создание кастомного эндпоинта для получения постов с дополнительной логикой

Допустим, вы хотите создать эндпоинт, который возвращает последние посты определённой категории с кастомной структурой данных. Вот пример:

add_action('rest_api_init', function () {
    register_rest_route('wptest/v1', '/posts-by-category', array(
        'methods' => 'GET',
        'callback' => 'wptest_get_posts_by_category',
        'args' => array(
            'category' => array(
                'required' => true,
                'validate_callback' => function($param) {
                    return is_string($param) && !empty($param);
                },
            ),
            'limit' => array(
                'required' => false,
                'default' => 5,
                'validate_callback' => function($param) {
                    return is_numeric($param) && $param > 0 && $param <= 20;
                },
            ),
        ),
    ));
});

function wptest_get_posts_by_category(WP_REST_Request $request) {
    $category = sanitize_text_field($request->get_param('category'));
    $limit = intval($request->get_param('limit'));

    $query = new WP_Query(array(
        'category_name' => $category,
        'posts_per_page' => $limit,
        'post_status' => 'publish',
    ));

    $posts = array();
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $posts[] = array(
                'id' => get_the_ID(),
                'title' => get_the_title(),
                'excerpt' => get_the_excerpt(),
                'link' => get_permalink(),
                'date' => get_the_date('c'),
            );
        }
        wp_reset_postdata();
    }

    return new WP_REST_Response(array('posts' => $posts), 200);
}

Такой эндпоинт позволяет получить удобный JSON для фронтенда или внешнего сервиса, возвращая только нужные поля и фильтруя по категории.

Безопасность: проверка прав доступа и авторизация

При создании REST API важно контролировать, кто может обращаться к эндпоинтам, особенно если они изменяют данные или возвращают конфиденциальную информацию. В WordPress для этого используется параметр permission_callback.

Например, чтобы разрешить доступ только авторизованным пользователям:

register_rest_route('wptest/v1', '/private-data', array(
    'methods' => 'GET',
    'callback' => 'wptest_private_data',
    'permission_callback' => function () {
        return is_user_logged_in();
    },
));

function wptest_private_data() {
    // Возвращаем приватные данные
    return new WP_REST_Response(array('secret' => 'Только для авторизованных!'), 200);
}

Вы можете реализовать более сложные проверки, например, проверять роли пользователя или использовать nonce.

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

Для упрощения создания и тестирования REST API в WordPress рекомендуем обратить внимание на следующие плагины:

WP REST API Controller — позволяет управлять доступом к стандартным REST API эндпоинтам и настраивать поля.
WPGraphQL — добавляет GraphQL API поверх WordPress, альтернативу REST.
JWT Authentication for WP REST API — реализует авторизацию с помощью JWT-токенов.
REST API Toolbox — расширяет возможности REST API, добавляя фильтры и хуки.

Отладка и тестирование кастомных эндпоинтов

Для отладки удобно использовать инструменты вроде Postman или curl. Пример запроса:

curl -X GET 'https://ваш-сайт.ru/wp-json/wptest/v1/posts-by-category?category=news&limit=3'

Также можно добавить временный error_log() внутри callback-функций для проверки значений параметров или логики.

Важно помнить, что при добавлении кастомных эндпоинтов и работе с API следует тщательно проверять и фильтровать входящие данные, чтобы избежать уязвимостей.