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

WordPress REST API значительно расширяет возможности взаимодействия с сайтом, позволяя создавать собственные кастомные эндпоинты. Это особенно полезно, когда стандартных маршрутов недостаточно для решения специфических задач, например, при интеграции с внешними сервисами или создании SPA (Single Page Application).

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

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

Кастомный эндпоинт — это новый URL, который принимает запросы и возвращает данные в формате JSON. Вы можете настроить методы (GET, POST, PUT, DELETE), параметры запроса, а также авторизацию.

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

Пример создания простого кастомного эндпоинта

Рассмотрим базовый пример, который возвращает список последних 5 постов определённой категории с кастомными полями.

add_action('rest_api_init', 'wpdemo_register_custom_route');
function wpdemo_register_custom_route() {
    register_rest_route('wpdemo/v1', '/latest-posts/', array(
        'methods' => 'GET',
        'callback' => 'wpdemo_get_latest_posts',
        'permission_callback' => '__return_true', // Доступно всем
    ));
}

function wpdemo_get_latest_posts(WP_REST_Request $request) {
    $args = array(
        'posts_per_page' => 5,
        'category_name' => 'news', // Замените на нужную категорию
        'post_status' => 'publish',
    );
    $query = new WP_Query($args);
    $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(),
                'custom_field' => get_post_meta(get_the_ID(), 'wpdemo_custom_field', true),
                'link' => get_permalink(),
            );
        }
        wp_reset_postdata();
    }
    return rest_ensure_response($posts);
}

В этом примере мы создали маршрут /wp-json/wpdemo/v1/latest-posts/, который возвращает JSON с информацией о последних 5 постах из категории "news".

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

Часто необходимо принимать параметры от клиента, чтобы фильтровать или сортировать данные. REST API позволяет это делать через объект WP_REST_Request.

Например, расширим предыдущий эндпоинт, добавив параметр category для выбора категории динамически.

add_action('rest_api_init', 'wpdemo_register_custom_route_with_params');
function wpdemo_register_custom_route_with_params() {
    register_rest_route('wpdemo/v1', '/latest-posts/', array(
        'methods' => 'GET',
        'callback' => 'wpdemo_get_latest_posts_with_params',
        'args' => array(
            'category' => array(
                'required' => false,
                'validate_callback' => function($param, $request, $key) {
                    return is_string($param) && !empty($param);
                },
                'sanitize_callback' => 'sanitize_text_field',
            ),
        ),
        'permission_callback' => '__return_true',
    ));
}

function wpdemo_get_latest_posts_with_params(WP_REST_Request $request) {
    $category = $request->get_param('category') ?: 'news';
    $args = array(
        'posts_per_page' => 5,
        'category_name' => $category,
        'post_status' => 'publish',
    );
    $query = new WP_Query($args);
    $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(),
            );
        }
        wp_reset_postdata();
    }
    return rest_ensure_response($posts);
}

Теперь, вызывая запрос GET /wp-json/wpdemo/v1/latest-posts/?category=technology, вы получите посты из категории "technology".

Авторизация и безопасность кастомных эндпоинтов

Открытые эндпоинты подходят не для всех случаев. Если данные должны быть доступны только авторизованным пользователям или с определёнными правами, нужно реализовать проверку в параметре permission_callback.

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

function wpdemo_permission_check() {
    return is_user_logged_in();
}

register_rest_route('wpdemo/v1', '/private-data/', array(
    'methods' => 'GET',
    'callback' => 'wpdemo_private_data_callback',
    'permission_callback' => 'wpdemo_permission_check',
));

function wpdemo_private_data_callback() {
    // Возвращаем приватные данные
    return rest_ensure_response(array('secret' => 'Это конфиденциальная информация'));
}

Для более сложной аутентификации можно использовать nonce, OAuth или JWT, но это выходит за рамки данной статьи.

Плагины для работы с REST API и расширением функционала

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

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

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

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

Для тестирования запросов удобно использовать инструменты типа Postman, Insomnia, или даже браузер для GET-запросов.

Если эндпоинт не работает, проверьте:

• Правильно ли зарегистрирован маршрут в хук rest_api_init.
• Возвращаются ли ошибки в формате JSON с описанием проблемы.
• Работает ли разрешение прав через permission_callback.
• Нет ли конфликтов с плагинами или темой.

Также включите WP_DEBUG и просматривайте логи ошибок.

Пример расширенного эндпоинта с POST-запросом

Для обработки POST-запросов, например, создания записи, необходимо добавить проверку nonce и прав пользователя:

add_action('rest_api_init', function () {
    register_rest_route('wpdemo/v1', '/create-post/', array(
        'methods' => 'POST',
        'callback' => 'wpdemo_create_post',
        'permission_callback' => function () {
            return current_user_can('edit_posts');
        },
        'args' => array(
            'title' => array(
                'required' => true,
                'sanitize_callback' => 'sanitize_text_field',
            ),
            'content' => array(
                'required' => true,
                'sanitize_callback' => 'wp_kses_post',
            ),
        ),
    ));
});

function wpdemo_create_post(WP_REST_Request $request) {
    $title = $request->get_param('title');
    $content = $request->get_param('content');

    $post_id = wp_insert_post(array(
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => 'pending', // Можно поставить 'publish'
        'post_type' => 'post',
    ));

    if (is_wp_error($post_id)) {
        return new WP_Error('post_creation_failed', 'Не удалось создать пост', array('status' => 500));
    }

    return rest_ensure_response(array('post_id' => $post_id, 'message' => 'Пост успешно создан'));
}

Такой эндпоинт можно использовать для создания записей через внешние приложения с учётом прав доступа.