Как создать собственную REST API в WordPress: практическое руководство

Автор: Алексей Смирнов | Опубликовано: 18.11.2025

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

Что такое REST API в WordPress и зачем создавать свои маршруты

REST API — это архитектурный стиль взаимодействия между клиентом и сервером через HTTP-запросы. В WordPress REST API позволяет работать с данными сайта (постами, пользователями, таксономиями) через стандартные HTTP-запросы (GET, POST, PUT, DELETE).

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

Примером может быть API для получения списка событий с дополнительной фильтрацией или API для управления пользовательскими настройками.

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

Для создания собственного маршрута используется функция register_rest_route(), которую нужно вызывать в хук rest_api_init. Рассмотрим базовый пример регистрации собственного маршрута.

add_action('rest_api_init', function () {
    register_rest_route('wpgenerate/v1', '/hello', [
        'methods' => 'GET',
        'callback' => 'wpgenerate_hello_callback',
    ]);
});

function wpgenerate_hello_callback(WP_REST_Request $request) {
    return [
        'message' => 'Привет из собственной REST API!',
        'timestamp' => time(),
    ];
}

Здесь мы регистрируем маршрут /wp-json/wpgenerate/v1/hello, который возвращает JSON с сообщением и текущим временем. Такой простой пример показывает базовый принцип работы.

Пояснения к параметрам register_rest_route

namespace — пространство имён, для группировки маршрутов (например, 'wpgenerate/v1'), рекомендуется использовать свой префикс.
route — путь маршрута (например, '/hello').
methods — HTTP-методы, которые поддерживает маршрут (GET, POST и др.).
callback — функция-обработчик запроса.

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

Для реальных задач часто нужны параметры запроса. Их можно получить из объекта WP_REST_Request через методы get_param(), get_params(), get_query_params().

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

add_action('rest_api_init', function () {
    register_rest_route('wpgenerate/v1', '/greet', [
        'methods' => 'GET',
        'callback' => 'wpgenerate_greet_callback',
        'args' => [
            'name' => [
                'required' => true,
                'validate_callback' => function ($param, $request, $key) {
                    return is_string($param) && strlen($param) <= 50;
                },
                'sanitize_callback' => 'sanitize_text_field',
            ],
        ],
    ]);
});

function wpgenerate_greet_callback(WP_REST_Request $request) {
    $name = $request->get_param('name');
    return ['message' => "Привет, " . $name . "!"];
}

В этом примере параметр name обязателен, должен быть строкой не длиннее 50 символов, и автоматически очищается функцией sanitize_text_field.

Методы POST и работа с данными

Для создания, обновления или удаления данных обычно используются методы POST, PUT, DELETE. Рассмотрим пример обработки POST-запроса, который создаёт кастомный пост типа 'event'.

add_action('rest_api_init', function () {
    register_rest_route('wpgenerate/v1', '/event', [
        'methods' => 'POST',
        'callback' => 'wpgenerate_create_event',
        'permission_callback' => function () {
            return current_user_can('edit_posts');
        },
        'args' => [
            'title' => [
                'required' => true,
                'sanitize_callback' => 'sanitize_text_field',
            ],
            'date' => [
                'required' => true,
                'validate_callback' => function ($param) {
                    return preg_match('/^\d{4}-\d{2}-\d{2}$/', $param);
                },
            ],
        ],
    ]);
});

function wpgenerate_create_event(WP_REST_Request $request) {
    $title = $request->get_param('title');
    $date = $request->get_param('date');

    $post_id = wp_insert_post([
        'post_type' => 'event',
        'post_title' => $title,
        'post_status' => 'publish',
        'meta_input' => ['event_date' => $date],
    ]);

    if (is_wp_error($post_id)) {
        return new WP_REST_Response(['error' => $post_id->get_error_message()], 500);
    }

    return ['success' => true, 'event_id' => $post_id];
}

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

Безопасность собственной REST API

Безопасность — ключевой момент при работе с API. Несколько советов:

Используйте permission_callback для проверки прав доступа.
Валидация и санитизация всех входящих данных.
Для публичных данных можно не требовать авторизации, но ограничьте методы.
Если нужна аутентификация, используйте JWT, OAuth или стандартные куки WordPress.

Пример проверки прав доступа в маршруте:

'permission_callback' => function () {
    return is_user_logged_in(); // Только для авторизованных
}

Проверка и отладка REST API

Для тестирования собственного API удобно использовать инструменты Postman, Insomnia или curl.

Пример curl-запроса:

curl -X GET https://your-site.ru/wp-json/wpgenerate/v1/hello

Если маршрут требует авторизации, добавьте заголовки с токеном или куки.

Также в WordPress есть встроенный лог ошибок, который поможет отловить проблемы в коде.

Пример расширенного маршрута с пагинацией и фильтрацией

Рассмотрим пример получения списка событий с параметрами пагинации и фильтрации по дате.

add_action('rest_api_init', function () {
    register_rest_route('wpgenerate/v1', '/events', [
        'methods' => 'GET',
        'callback' => 'wpgenerate_get_events',
        'args' => [
            'page' => [
                'default' => 1,
                'validate_callback' => 'is_numeric',
            ],
            'per_page' => [
                'default' => 10,
                'validate_callback' => function ($param) {
                    return is_numeric($param) && $param > 0 && $param <= 100;
                },
            ],
            'date' => [
                'validate_callback' => function ($param) {
                    return preg_match('/^\d{4}-\d{2}-\d{2}$/', $param);
                },
            ],
        ],
    ]);
});

function wpgenerate_get_events(WP_REST_Request $request) {
    $page = (int) $request->get_param('page');
    $per_page = (int) $request->get_param('per_page');
    $date = $request->get_param('date');

    $args = [
        'post_type' => 'event',
        'posts_per_page' => $per_page,
        'paged' => $page,
    ];

    if ($date) {
        $args['meta_query'] = [
            [
                'key' => 'event_date',
                'value' => $date,
                'compare' => '=',
            ],
        ];
    }

    $query = new WP_Query($args);

    $events = [];
    foreach ($query->posts as $post) {
        $events[] = [
            'id' => $post->ID,
            'title' => $post->post_title,
            'date' => get_post_meta($post->ID, 'event_date', true),
        ];
    }

    return [
        'events' => $events,
        'total' => $query->found_posts,
        'pages' => $query->max_num_pages,
    ];
}

Такой маршрут позволит клиенту удобно получать данные с учётом фильтров и навигации.

Заключение

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