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

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

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

Однако стандартный набор эндпойнтов WordPress ограничен основными типами данных: посты, страницы, пользователи и т.д. Часто возникает необходимость расширить API, добавив собственные эндпойнты, которые будут возвращать специфическую информацию или выполнять кастомную логику. Например, получить список последних заказов в WooCommerce, вывести данные из пользовательских таблиц или реализовать авторизацию с дополнительной проверкой.

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

Регистрация кастомного эндпойнта: базовые шаги

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

• namespace — пространство имён для группы маршрутов, например wpco/v1;
• route — путь эндпойнта, например /custom-data;
• args — массив с настройками эндпойнта: методы, callback-функция, права доступа и др.

Пример регистрации простого GET эндпойнта:

add_action('rest_api_init', function() {
    register_rest_route('wpco/v1', '/custom-data', array(
        'methods' => 'GET',
        'callback' => 'wpco_get_custom_data',
        'permission_callback' => function () {
            return current_user_can('read');
        }
    ));
});

function wpco_get_custom_data(WP_REST_Request $request) {
    return [
        'status' => 'success',
        'data' => 'Это пример кастомного эндпойнта REST API в WordPress'
    ];
}

Этот код добавит новый URL вида /wp-json/wpco/v1/custom-data, который при запросе вернёт JSON-ответ с сообщением.

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

Часто необходимо получать параметры из URL или тела запроса. REST API позволяет удобно работать с параметрами через объект WP_REST_Request. Например, можно получить параметр id из URL:

function wpco_get_custom_data(WP_REST_Request $request) {
    $id = $request->get_param('id');
    if (!is_numeric($id)) {
        return new WP_Error('invalid_id', 'Параметр id должен быть числом', array('status' => 400));
    }
    // Логика обработки $id
    return [ 'id' => $id, 'message' => 'Данные успешно получены' ];
}

Чтобы объявить параметры и их валидацию на уровне регистрации, используют аргумент args в register_rest_route():

register_rest_route('wpco/v1', '/custom-data', array(
    'methods' => 'GET',
    'callback' => 'wpco_get_custom_data',
    'permission_callback' => function() { return true; },
    'args' => array(
        'id' => array(
            'required' => true,
            'validate_callback' => function($param) {
                return is_numeric($param);
            }
        )
    )
));

Так WordPress автоматически проверит параметры запроса и вернёт ошибку при некорректных данных.

Создание POST эндпойнта: приём и обработка данных

Для записи данных в WordPress через REST API используют метод POST. Рассмотрим пример эндпойнта, который принимает JSON с пользовательскими данными и создаёт новый пост типа «custom_post».

add_action('rest_api_init', function() {
    register_rest_route('wpco/v1', '/add-post', array(
        'methods' => 'POST',
        'callback' => 'wpco_add_custom_post',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        },
        'args' => array(
            'title' => array(
                'required' => true,
                'validate_callback' => function($param) {
                    return is_string($param) && !empty($param);
                }
            ),
            'content' => array(
                'required' => false,
            )
        )
    ));
});

function wpco_add_custom_post(WP_REST_Request $request) {
    $title = sanitize_text_field($request->get_param('title'));
    $content = sanitize_textarea_field($request->get_param('content'));

    $post_id = wp_insert_post(array(
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => 'publish',
        'post_type' => 'custom_post'
    ));

    if (is_wp_error($post_id)) {
        return new WP_Error('post_creation_failed', 'Ошибка при создании записи', array('status' => 500));
    }

    return [
        'status' => 'success',
        'post_id' => $post_id
    ];
}

Обратите внимание на проверку прав пользователя через permission_callback. Это важный момент для безопасности API.

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

Хотя WordPress имеет мощный встроенный REST API, существуют плагины, которые помогут расширить возможности или упростить разработку:

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

Эти плагины полезны, если ваша задача — сделать API более гибким и безопасным без глубокого переписывания кода.

Практические советы по безопасности и производительности REST API

При создании кастомных эндпойнтов важно учитывать вопросы безопасности:

• Всегда используйте permission_callback, чтобы ограничивать доступ по ролям или другим критериям.
• Валидация и санитизация входящих данных — обязательный этап, чтобы избежать инъекций и ошибок.
• Не раскрывайте лишнюю информацию в ответах, особенно данные пользователей и системные детали.
• Для ресурсоёмких запросов используйте кеширование, чтобы снизить нагрузку на сервер.

Кроме того, тестируйте API с помощью инструментов типа Postman или Insomnia, чтобы убедиться в корректности работы и безопасности.

Как отлаживать кастомные REST API эндпойнты в WordPress

Для отладки полезно включить WP_DEBUG и WP_DEBUG_LOG в wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Ошибки будут сохраняться в wp-content/debug.log. Также можно выводить данные в ответах временно, чтобы проверить внутренние переменные.

Для просмотра и тестирования запросов удобно использовать REST API клиент (Postman, Insomnia), или браузер, если это GET запросы.

Также полезно логировать входящие запросы и ответы, если API используется в продакшене, для анализа и мониторинга.

Заключение: расширяйте возможности WordPress с кастомными REST API эндпойнтами

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

Главное — соблюдать правила безопасности, правильно обрабатывать входящие данные и организовывать код так, чтобы его было легко поддерживать. Приведённые примеры и советы помогут быстро начать работу и избежать распространённых ошибок.