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

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

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

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

• Предоставлять специализированные данные, не представленные в стандартных эндпоинтах;
• Выполнять сложные действия или бизнес-логику через API;
• Интегрировать внешний сервис с вашим сайтом;
• Создавать интерфейсы для SPA или мобильных приложений с кастомной логикой.

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

Регистрация кастомного REST API маршрута в WordPress

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

add_action('rest_api_init', 'wpcommunity_register_custom_route');
function wpcommunity_register_custom_route() {
    register_rest_route('wpcommunity/v1', '/hello/', [
        'methods' => 'GET',
        'callback' => 'wpcommunity_hello_endpoint',
        'permission_callback' => '__return_true', // пока без проверки прав
    ]);
}

function wpcommunity_hello_endpoint(WP_REST_Request $request) {
    return [
        'message' => 'Привет из кастомного REST API эндпоинта!'
    ];
}

В этом примере мы создали маршрут /wp-json/wpcommunity/v1/hello/, который при GET-запросе возвращает простое сообщение. Параметр permission_callback отвечает за проверку прав доступа. В данном случае __return_true означает, что доступ открыт всем.

Пояснение параметров register_rest_route

• namespace (wpcommunity/v1) — уникальный префикс для вашего API, чтобы не пересекаться с другими;
• route (/hello/) — путь после namespace, формирующий полный URL;
• methods — HTTP методы, например GET, POST;
• callback — функция, которая обрабатывает запрос и возвращает данные;
• permission_callback — функция, проверяющая права доступа.

Добавление параметров и обработка входных данных

Часто нужно принимать параметры от клиента, например, ID поста или фильтры. Их можно получить через объект WP_REST_Request. Вот пример endpoint, который принимает параметр name:

add_action('rest_api_init', 'wpcommunity_register_greet_route');
function wpcommunity_register_greet_route() {
    register_rest_route('wpcommunity/v1', '/greet/', [
        'methods' => 'GET',
        'callback' => 'wpcommunity_greet_endpoint',
        'args' => [
            'name' => [
                'required' => true,
                'validate_callback' => function($param) {
                    return is_string($param) && !empty($param);
                },
            ],
        ],
        'permission_callback' => '__return_true',
    ]);
}

function wpcommunity_greet_endpoint(WP_REST_Request $request) {
    $name = sanitize_text_field($request->get_param('name'));
    return [
        'message' => "Привет, {$name}! Добро пожаловать в WPCommunity REST API."
    ];
}

В данном случае, если не передать параметр name, WordPress автоматически вернёт ошибку. Также предусмотрена валидация параметров через validate_callback.

Обеспечение безопасности кастомных эндпоинтов

Очень важно контролировать, кто и что может вызвать ваши REST API маршруты. Для этого используется параметр permission_callback. Вот примеры:

• Доступ только для авторизованных пользователей:

'permission_callback' => function() {
    return is_user_logged_in();
}

• Доступ только для пользователей с правом 'edit_posts':

'permission_callback' => function() {
    return current_user_can('edit_posts');
}

Также можно проверять nonce, токены или любые другие способы аутентификации. Например, если API используется для внешнего сервиса, можно реализовать авторизацию по API ключу.

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

Предположим, нужно создать endpoint, который возвращает список последних заказов пользователя (представим, что у вас кастомная таблица или метаданные). Вот пример:

add_action('rest_api_init', 'wpcommunity_register_user_orders_route');
function wpcommunity_register_user_orders_route() {
    register_rest_route('wpcommunity/v1', '/user-orders/', [
        'methods' => 'GET',
        'callback' => 'wpcommunity_user_orders_endpoint',
        'permission_callback' => function() {
            return is_user_logged_in();
        },
    ]);
}

function wpcommunity_user_orders_endpoint(WP_REST_Request $request) {
    $user_id = get_current_user_id();
    if (!$user_id) {
        return new WP_Error('no_user', 'Пользователь не авторизован', ['status' => 401]);
    }

    // Пример получения заказов из пользовательских метаданных или таблицы
    $orders = get_user_meta($user_id, 'wpcommunity_orders', true);

    if (empty($orders)) {
        return [];
    }

    return ['orders' => $orders];
}

Этот endpoint возвращает данные только авторизованному пользователю. В реальном проекте нужно заменить получение заказов на запросы из базы или другого источника.

Интеграция с плагинами WPShop для расширения REST API

Если вы используете плагины из WPShop.ru, например, Expert Review для отзывов или WPRemark для комментариев, вы можете расширять их функционал через REST API.

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

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

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

• Postman — мощный клиент для тестирования HTTP-запросов;
• cURL — командная строка для отправки запросов;
• Встроенный браузер или консоль разработчика в браузере.

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

Выводы и рекомендации

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

Используйте префиксы и неймспейсы, чтобы избежать конфликтов, валидируйте параметры, и не забывайте про проверку прав пользователей. При правильном подходе REST API станет надежной основой для развития вашего проекта.