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

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

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

Создание кастомных REST API эндпоинтов позволяет интегрировать WordPress с внешними сервисами, создавать одностраничные приложения (SPA), настраивать мобильные приложения и решать нестандартные бизнес-задачи, которые нельзя закрыть штатными методами.

Далее разберем, как правильно создавать кастомные эндпоинты, регистрировать маршруты и обрабатывать запросы с примерами кода.

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

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

• namespace — пространство имён, чтобы отделить ваши маршруты от стандартных. Обычно используют формат plugin/v1 или custom/v1.
• route — путь эндпоинта, например, /data или /user/(?P<id>>\d+) для динамических параметров.
• args — массив с настройками, где задаются методы (GET, POST), колбеки для обработки, параметры и права доступа.

Пример простой регистрации эндпоинта, который возвращает список последних 5 постов:

add_action('rest_api_init', 'wordpressy_register_custom_endpoint');
function wordpressy_register_custom_endpoint() {
    register_rest_route('wordpressy/v1', '/latest-posts', [
        'methods'  => 'GET',
        'callback' => 'wordpressy_get_latest_posts',
        'permission_callback' => '__return_true' // доступ открыт всем
    ]);
}

function wordpressy_get_latest_posts() {
    $posts = get_posts(['numberposts' => 5]);
    $data = [];
    foreach ($posts as $post) {
        $data[] = [
            'id'    => $post->ID,
            'title' => get_the_title($post),
            'link'  => get_permalink($post),
        ];
    }
    return $data;
}

Такой эндпоинт доступен по URL https://ваш-сайт.ru/wp-json/wordpressy/v1/latest-posts.

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

Часто нужно принимать параметры от клиента, например, ID записи или фильтры. Для этого в register_rest_route в аргументах можно определить args — массив с правилами валидации и фильтрации.

Например, добавим эндпоинт, который возвращает данные конкретного поста по ID, передаваемому в URL:

add_action('rest_api_init', 'wordpressy_register_post_endpoint');
function wordpressy_register_post_endpoint() {
    register_rest_route('wordpressy/v1', '/post/(?P<id>>\d+)', [
        'methods'  => 'GET',
        'callback' => 'wordpressy_get_post_by_id',
        'args'     => [
            'id' => [
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param) && $param > 0;
                }
            ]
        ],
        'permission_callback' => function() {
            return current_user_can('read');
        }
    ]);
}

function wordpressy_get_post_by_id($request) {
    $id = (int) $request->get_param('id');
    $post = get_post($id);
    if (!$post) {
        return new WP_Error('not_found', 'Пост не найден', ['status' => 404]);
    }
    return [
        'id'      => $post->ID,
        'title'   => get_the_title($post),
        'content' => apply_filters('the_content', $post->post_content),
    ];
}

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

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

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

Рассмотрим пример эндпоинта, который позволяет зарегистрированному пользователю создать новую запись типа 'post' с заголовком и содержимым из JSON тела запроса:

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

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

    $post_id = wp_insert_post([
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'draft',
        'post_author'  => get_current_user_id(),
    ]);

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

    return ['post_id' => $post_id, 'message' => 'Пост успешно создан'];
}

В этом примере важно правильно санитизировать входящие данные и контролировать права. Используйте sanitize_text_field для заголовков и wp_kses_post для содержимого, чтобы не допустить вредоносного кода.

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

Для упрощения разработки и тестирования REST API в WordPress можно использовать несколько полезных плагинов:

• WP REST API Console — позволяет отправлять запросы к REST API прямо из админки и быстро проверять ответы.
• JWT Authentication for WP REST API — добавляет поддержку авторизации через JWT-токены, что удобно для мобильных и SPA приложений.
• Advanced Custom Fields (ACF) — позволяет создавать кастомные поля и удобно добавлять их в REST API через официальное расширение ACF to REST API.

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

Заключение по созданию кастомных REST API эндпоинтов в WordPress

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

В статье показаны базовые приёмы регистрации маршрутов, обработки параметров, проверки прав и создания данных через POST-запросы. Используйте примеры как шаблон для собственных задач, тщательно продумывайте структуру маршрутов и безопасность.

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