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

Автор: Дмитрий Сорокин | Опубликовано: 01.12.2025

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

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

REST API endpoint — это URL, по которому ваш сайт принимает запросы и возвращает данные в формате JSON. Обычно WordPress уже имеет множество встроенных endpoint'ов: для постов, пользователей, таксономий и т.д. Но что если нужно предоставить доступ к кастомным данным, например, к метаданным или результатам сложных запросов? Тогда создаём собственный endpoint.

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

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

В итоге вы получаете гибкий инструмент для разработки и масштабирования проектов.

Как зарегистрировать собственный REST API endpoint в WordPress

Для создания собственного endpoint используется хук rest_api_init. Внутри него вызывается функция регистрации маршрута register_rest_route(). Рассмотрим простейший пример регистрации endpoint с namespace 'wpquery/v1' и маршрутом 'custom-data'.

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

function wpquery_handle_custom_data_request(WP_REST_Request $request) {
    // Логика обработки запроса
    return new WP_REST_Response(array('message' => 'Данные успешно получены'), 200);
}

В этом коде мы определили маршрут /wp-json/wpquery/v1/custom-data/, который будет отвечать на GET-запросы. Внутри callback-функции можно реализовать любую логику.

Параметры функции `register_rest_route`

Обратите внимание на ключевые параметры:

methods — HTTP-метод, может быть строкой или массивом методов;
callback — функция, которая обрабатывает запрос и возвращает данные;
permission_callback — функция проверки прав доступа, обязательна для безопасности API.

Если не определить permission_callback, endpoint будет доступен всем, что небезопасно.

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

Часто необходимо передавать параметры в запросе, например, ID записи или фильтры. В WordPress REST API параметры доступны через объект WP_REST_Request.

Пример обработки GET-параметра post_id:

function wpquery_handle_custom_data_request(WP_REST_Request $request) {
    $post_id = $request->get_param('post_id');
    if (!$post_id) {
        return new WP_Error('no_post_id', 'Не передан параметр post_id', array('status' => 400));
    }
    $post = get_post($post_id);
    if (!$post) {
        return new WP_Error('invalid_post', 'Пост не найден', array('status' => 404));
    }

    $data = array(
        'ID' => $post->ID,
        'title' => $post->post_title,
        'content' => $post->post_content,
    );
    return new WP_REST_Response($data, 200);
}

Так мы возвращаем информацию о посте по его ID. Если параметр не передан или пост не найден — возвращаем ошибку с соответствующим HTTP-кодом.

Добавление поддержки POST-запросов и создание записи через API

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

add_action('rest_api_init', 'wpquery_register_post_creation_endpoint');
function wpquery_register_post_creation_endpoint() {
    register_rest_route('wpquery/v1', '/create-post/', array(
        'methods'  => 'POST',
        'callback' => 'wpquery_handle_create_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' => true,
                'validate_callback' => function($param) {
                    return is_string($param);
                }
            ),
        ),
    ));
}

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

    $new_post = array(
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'draft',
        'post_author'  => get_current_user_id(),
    );

    $post_id = wp_insert_post($new_post);

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

    return new WP_REST_Response(array('post_id' => $post_id, 'message' => 'Пост успешно создан'), 201);
}

Здесь мы используем валидацию аргументов, чтобы гарантировать корректность данных. Созданный пост получает статус черновика, а автором становится текущий пользователь.

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

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

WP REST API Controller — позволяет управлять доступом и полями данных в стандартных endpoint'ах через удобный интерфейс;
Advanced Custom Fields (ACF) to REST API — добавляет поддержку пользовательских полей ACF в REST API;
REST API Toolbox — расширяет возможности настройки и добавления новых маршрутов;
JWT Authentication for WP REST API — добавляет поддержку аутентификации через JSON Web Tokens, что удобно для защищённого доступа к API.

Эти инструменты значительно упрощают работу с API, но для уникальных бизнес-задач лучше писать собственные endpoint'ы, как показано выше.

Безопасность и производительность кастомных REST API endpoint'ов

При создании собственных endpoint важно помнить про безопасность:

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

Для повышения производительности можно использовать кэширование ответов через Transients API или внешние системы кэширования.

Итог: почему создание уникальных REST API endpoint важно для современного WordPress-разработчика

Расширение стандартных возможностей WordPress с помощью собственных REST API endpoint'ов позволяет создавать гибкие, масштабируемые и безопасные решения для самых разных задач. Это критично при разработке мобильных приложений, SPA, интеграций с внешними системами и автоматизации внутренних процессов.

Используйте приведённые примеры как отправную точку для своих проектов и не забывайте про безопасность и оптимизацию.