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

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

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

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

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

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

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

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

add_action('rest_api_init', function() {
    register_rest_route('wpelement/v1', '/top-posts/', array(
        'methods' => 'GET',
        'callback' => 'wpelement_get_top_posts',
        'args' => array(
            'min_rating' => array(
                'required' => false,
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param);
                }
            ),
        ),
        'permission_callback' => '__return_true',
    ));
});

function wpelement_get_top_posts(WP_REST_Request $request) {
    $min_rating = $request->get_param('min_rating') ?: 0;
    $args = array(
        'post_type' => 'post',
        'meta_query' => array(
            array(
                'key' => 'rating',
                'value' => $min_rating,
                'compare' => '>=',
                'type' => 'NUMERIC'
            )
        ),
        'posts_per_page' => 10,
        'orderby' => 'meta_value_num',
        'meta_key' => 'rating',
        'order' => 'DESC',
    );
    $query = new WP_Query($args);
    $posts = [];
    foreach ($query->posts as $post) {
        $posts[] = array(
            'id' => $post->ID,
            'title' => get_the_title($post),
            'rating' => get_post_meta($post->ID, 'rating', true),
            'link' => get_permalink($post),
        );
    }
    return rest_ensure_response($posts);
}

В этом примере создан маршрут /wp-json/wpelement/v1/top-posts/, который принимает необязательный параметр min_rating и возвращает топ-10 постов с рейтингом выше этого значения.

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

Очень важно грамотно обрабатывать входящие параметры и валидировать их, чтобы избежать ошибок и потенциальных уязвимостей. В примере выше для параметра min_rating используется validate_callback, возвращающий true только если параметр числовой.

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

Для сложных фильтров и параметров рекомендуется использовать объекты WP_REST_Request и методы для получения параметров, как в функции wpelement_get_top_posts.

Контроль доступа и безопасность кастомных эндпоинтов

Параметр permission_callback отвечает за проверку прав пользователя или авторизацию перед выполнением запроса. В простом примере стоит __return_true, то есть эндпоинт доступен всем. Но в реальных проектах часто необходима проверка прав, например:

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

Это ограничит доступ к эндпоинту только авторизованным пользователям с правом редактировать записи. Можно реализовать и более сложные сценарии, например, проверку nonce, токенов или OAuth.

Пример проверки авторизации по пользовательскому токену

Если вы используете собственную систему авторизации, например, передаёте токен в заголовке, можно реализовать проверку так:

function wpelement_permission_check(WP_REST_Request $request) {
    $token = $request->get_header('X-WPELEMENT-TOKEN');
    if (!$token || !wpelement_validate_token($token)) {
        return new WP_Error('rest_forbidden', 'Доступ запрещён', array('status' => 403));
    }
    return true;
}

И подключить в register_rest_route:

'permission_callback' => 'wpelement_permission_check'

Использование плагинов для расширения возможностей REST API

Для удобства можно использовать готовые решения. Например, плагин Clearfy Pro позволяет расширять функционал и оптимизировать API, а WPCommunity помогает создавать более продвинутые пользовательские взаимодействия через API.

Также полезен плагин WPGPT для генерации кода и автоматизации создания сложных эндпоинтов с помощью AI.

Обработка POST-запросов и создание новых записей через REST API

Кроме получения данных, REST API позволяет создавать и обновлять записи. Для примера создадим эндпоинт, который принимает POST-запрос с данными и создаёт новый кастомный пост типа "review".

add_action('rest_api_init', function() {
    register_rest_route('wpelement/v1', '/add-review/', array(
        'methods' => 'POST',
        'callback' => 'wpelement_add_review',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        },
        'args' => array(
            'title' => array('required' => true),
            'content' => array('required' => true),
            'rating' => array(
                'required' => true,
                'validate_callback' => function($param) {
                    return is_numeric($param) && $param >= 1 && $param <= 5;
                }
            ),
        ),
    ));
});

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

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

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

    update_post_meta($post_id, 'rating', $rating);

    return rest_ensure_response(array('success' => true, 'post_id' => $post_id));
}

Этот эндпоинт проверяет права пользователя, валидирует входные данные и создаёт запись с мета-полем рейтинга. Это классический пример расширения API для пользовательского контента.

Логирование и отладка REST API запросов

При разработке кастомных эндпоинтов важно вести логирование запросов и ошибок. Можно использовать стандартный PHP лог или расширенные решения, например, error_log() внутри функций:

error_log('REST API wpelement: получен запрос с параметром min_rating=' . $min_rating);

Для более глубокого анализа полезен плагин Clearfy Pro, который позволяет мониторить и оптимизировать REST API вызовы, а также отключать ненужные маршруты для повышения безопасности.

Выводы и рекомендации по созданию кастомных REST API эндпоинтов

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

• Чётко проектировать структуру маршрутов и параметры;
• Валидировать и санитизировать входящие данные;
• Обеспечивать контроль доступа и безопасность;
• Использовать хуки и фильтры для гибкой настройки;
• Логировать и тестировать работу эндпоинтов;
• При необходимости применять готовые плагины для упрощения задач.

Если вы хотите подробнее изучить REST API и получить готовые решения — рекомендуем ознакомиться с плагинами из WPShop и их документацией.