Как создать собственный REST API endpoint в WordPress: пошаговое руководство

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

Что такое REST API endpoint в WordPress и зачем он нужен

REST API endpoint — это точка доступа к данным или функционалу сайта через HTTP-запросы (GET, POST, PUT, DELETE и др.). Создавая собственный endpoint, вы расширяете возможности взаимодействия с сайтом, например, для мобильного приложения, внешних сервисов или SPA (Single Page Application).

Создание кастомного endpoint позволяет:

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

Давайте перейдём к практике.

Регистрация собственного REST API endpoint в WordPress

Для регистрации собственного endpoint используется функция register_rest_route(). Обычно это делают на хуке rest_api_init. Рассмотрим пример создания endpoint, который возвращает список последних 5 постов определённого типа.

Пример регистрации endpoint

add_action('rest_api_init', 'wp2_register_custom_endpoint');
function wp2_register_custom_endpoint() {
    register_rest_route('wp2/v1', '/latest-posts/', array(
        'methods' => 'GET',
        'callback' => 'wp2_get_latest_posts',
        'permission_callback' => '__return_true', // Для демонстрации
    ));
}

function wp2_get_latest_posts(WP_REST_Request $request) {
    $args = array(
        'post_type' => 'post',
        'posts_per_page' => 5,
        'post_status' => 'publish',
    );
    $query = new WP_Query($args);
    $posts = array();

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

    return rest_ensure_response($posts);
}

В этом примере мы создали endpoint по адресу /wp-json/wp2/v1/latest-posts/, который возвращает JSON с последними 5 опубликованными постами.

Обработка параметров запроса и безопасность REST API

Часто нужно принимать параметры в endpoint, например, количество постов или тип поста. Параметры можно получить из объекта WP_REST_Request. К тому же важно соблюдать безопасность и проверять права доступа.

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

add_action('rest_api_init', 'wp2_register_param_endpoint');
function wp2_register_param_endpoint() {
    register_rest_route('wp2/v1', '/posts/', array(
        'methods' => 'GET',
        'callback' => 'wp2_get_posts_with_params',
        'permission_callback' => function() {
            return current_user_can('read');
        },
        'args' => array(
            'count' => array(
                'required' => false,
                'default' => 5,
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param) && $param > 0 && $param <= 20;
                },
            ),
            'post_type' => array(
                'required' => false,
                'default' => 'post',
                'sanitize_callback' => 'sanitize_text_field',
            ),
        ),
    ));
}

function wp2_get_posts_with_params(WP_REST_Request $request) {
    $count = (int) $request->get_param('count');
    $post_type = $request->get_param('post_type');

    $args = array(
        'post_type' => $post_type,
        'posts_per_page' => $count,
        'post_status' => 'publish',
    );

    $query = new WP_Query($args);
    $posts = array();

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

    return rest_ensure_response($posts);
}

В этом коде мы добавили параметры count и post_type с валидацией и санитизацией. Также проверяем, что пользователь имеет право читать контент.

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

Для расширения функционала REST API можно использовать готовые плагины:

WP REST API Controller — удобный интерфейс для управления доступными полями и маршрутами API.
Custom Post Type REST API — расширяет API для кастомных типов записей.
JWT Authentication for WP REST API — добавляет JWT аутентификацию для безопасного доступа.

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

Расширение функционала: создание POST-запроса для сохранения данных

REST API позволяет не только получать данные, но и отправлять их на сервер. Рассмотрим пример создания endpoint, который принимает данные через POST и сохраняет новую запись.

add_action('rest_api_init', 'wp2_register_post_endpoint');
function wp2_register_post_endpoint() {
    register_rest_route('wp2/v1', '/add-post/', array(
        'methods' => 'POST',
        'callback' => 'wp2_handle_add_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 wp2_handle_add_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',
        '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));
}

В данном примере мы создаём endpoint /wp-json/wp2/v1/add-post/, который принимает заголовок и контент поста, проверяет права пользователя и создаёт новую запись со статусом pending.

Советы по отладке и тестированию кастомных REST API endpoint

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

Postman — мощный GUI для отправки запросов и просмотра ответов;
cURL — командная строка для быстрого тестирования;
WP-CLI — для проверки через консоль WordPress.

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

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