Создание кастомных REST API эндпоинтов в WordPress: подробный гайд

Автор: Николай Титов | Опубликовано: 24.11.2025

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

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

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

Кастомные эндпоинты позволяют:

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

Для создания таких эндпоинтов в WordPress используется функция register_rest_route(), которая регистрирует маршрут с указанием методов, коллбеков и прав доступа.

Регистрация собственного REST API маршрута: базовый пример

Для начала создадим простой маршрут, который отдаёт приветствие. Регистрировать маршруты нужно в хуке rest_api_init. Вот минимальный пример кода, который можно добавить в файл functions.php темы или в свой плагин:

add_action('rest_api_init', 'wpeducation_register_hello_route');
function wpeducation_register_hello_route() {
    register_rest_route('wpeducation/v1', '/hello/', [
        'methods' => 'GET',
        'callback' => 'wpeducation_hello_world',
        'permission_callback' => '__return_true',
    ]);
}

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

Объяснение:

wpeducation/v1 — это namespace и версия API.
/hello/ — путь маршрута.
methods — HTTP метод (GET).
callback — функция, которая вернёт данные.
permission_callback — функция проверки прав доступа (здесь всегда true, доступ открыт).

После добавления можно проверить эндпоинт, обратившись к https://ваш-сайт.ru/wp-json/wpeducation/v1/hello/. Вы получите JSON с сообщением.

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

Часто нужно принимать параметры из URL или тела запроса. Рассмотрим, как принимать параметр и валидировать его.

add_action('rest_api_init', 'wpeducation_register_greet_route');
function wpeducation_register_greet_route() {
    register_rest_route('wpeducation/v1', '/greet/(?P<name>[a-zA-Z0-9-]+)', [
        'methods' => 'GET',
        'callback' => 'wpeducation_greet_user',
        'permission_callback' => '__return_true',
        'args' => [
            'name' => [
                'validate_callback' => function($param, $request, $key) {
                    return is_string($param) && strlen($param) > 0;
                }
            ]
        ]
    ]);
}

function wpeducation_greet_user(WP_REST_Request $request) {
    $name = $request->get_param('name');
    return [ 'message' => "Привет, {$name}! Добро пожаловать в кастомный REST API." ];
}

Здесь мы добавили параметр name в URL, который валидируем, чтобы он был строкой и не пустым. Если валидация не пройдёт, WordPress вернёт ошибку 400.

Создание маршрута для POST-запроса с обработкой данных

Для приёма данных от клиента обычно используют POST-запросы. Сделаем пример, который принимает JSON с полем email и сохраняет его в опцию WordPress.

add_action('rest_api_init', 'wpeducation_register_save_email_route');
function wpeducation_register_save_email_route() {
    register_rest_route('wpeducation/v1', '/save-email', [
        'methods' => 'POST',
        'callback' => 'wpeducation_save_email',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        },
        'args' => [
            'email' => [
                'required' => true,
                'validate_callback' => function($email) {
                    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
                }
            ]
        ]
    ]);
}

function wpeducation_save_email(WP_REST_Request $request) {
    $email = $request->get_param('email');
    update_option('wpeducation_saved_email', sanitize_email($email));
    return [ 'success' => true, 'email' => $email ];
}

В этом примере:

Проверяется, что пользователь имеет право edit_posts (например, автор или админ).
Валидация email через PHP-фильтр.
Сохранение email в опцию базы данных.

Работа с кастомными типами записей через REST API

Если у вас есть кастомный тип записи, например, course, вы можете расширить стандартный REST API или создать отдельный эндпоинт для сложных запросов.

Для того, чтобы кастомный тип записи поддерживал REST API по умолчанию, нужно при регистрации CPT указать show_in_rest => true:

function wpeducation_register_course_cpt() {
    register_post_type('course', [
        'label' => 'Курсы',
        'public' => true,
        'show_in_rest' => true,
        'supports' => ['title', 'editor', 'custom-fields'],
    ]);
}
add_action('init', 'wpeducation_register_course_cpt');

После этого WordPress создаст стандартные маршруты для CPT, например, /wp-json/wp/v2/course/. Но иногда нужно получить курсы с дополнительной фильтрацией или метаданными.

Создадим кастомный эндпоинт, который отдаёт курсы с фильтром по метаполю level:

add_action('rest_api_init', 'wpeducation_register_courses_filtered_route');
function wpeducation_register_courses_filtered_route() {
    register_rest_route('wpeducation/v1', '/courses/', [
        'methods' => 'GET',
        'callback' => 'wpeducation_get_courses_by_level',
        'permission_callback' => '__return_true',
        'args' => [
            'level' => [
                'required' => false,
                'validate_callback' => function($param) {
                    return in_array($param, ['beginner', 'intermediate', 'advanced'], true);
                }
            ]
        ]
    ]);
}

function wpeducation_get_courses_by_level(WP_REST_Request $request) {
    $level = $request->get_param('level');
    $args = [
        'post_type' => 'course',
        'posts_per_page' => 10,
    ];
    if ($level) {
        $args['meta_query'] = [
            [
                'key' => 'level',
                'value' => $level,
                'compare' => '=',
            ]
        ];
    }
    $query = new WP_Query($args);
    $courses = [];
    foreach ($query->posts as $post) {
        $courses[] = [
            'id' => $post->ID,
            'title' => $post->post_title,
            'level' => get_post_meta($post->ID, 'level', true),
        ];
    }
    return $courses;
}

Практические советы и безопасность при работе с REST API

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

Правильно настраивайте permission_callback. Если данные публичные — можно возвращать __return_true, но если данные чувствительные — проверяйте права пользователя.
Валидация и санитизация данных из запроса обязательна для предотвращения инъекций и ошибок.
Обрабатывайте ошибки через выброс исключений или возвращайте WP_Error.
Кэшируйте результаты, если запросы тяжелые, чтобы снизить нагрузку.

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

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

WP REST API Controller — позволяет настраивать доступность полей и эндпоинтов без кода.
REST API Toolbox — расширяет функциональность и добавляет удобства.
Postman — хотя это не плагин, а приложение, оно незаменимо для тестирования REST API запросов.

Также, если нужно создавать сложные API, можно использовать фреймворки для WordPress, например, WP API или WPGraphQL для GraphQL, но это отдельная тема.