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

Автор: Павел Кузнецов | Опубликовано: 13.11.2025

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

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

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

Основные преимущества создания собственного REST API:

Гибкость — можно создавать любые маршруты и логику.
Безопасность — можно настроить авторизацию и права доступа.
Масштабируемость — API можно расширять по мере необходимости.

Разберём на практике, как создавать такие эндпоинты.

Как зарегистрировать кастомный REST API эндпоинт в WordPress

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

add_action('rest_api_init', function () {
    register_rest_route('wpcoding/v1', '/recent-posts', array(
        'methods' => 'GET',
        'callback' => 'wpcoding_get_recent_posts',
        'permission_callback' => '__return_true',
    ));
});

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

В этом примере мы создали маршрут /wp-json/wpcoding/v1/recent-posts, который возвращает JSON с пятью последними постами.

Объяснение параметров `register_rest_route`

Функция принимает три аргумента:

namespace — пространство имён, в примере wpcoding/v1. Рекомендуется использовать уникальное имя, связанное с вашим проектом.
route — путь эндпоинта, в примере /recent-posts.
args — массив параметров, включая методы HTTP, callback-функцию и проверку прав.

Добавление параметров и валидация данных в Custom REST API

Часто нужно принимать параметры от клиента, например, фильтры или данные для создания записи. Рассмотрим, как добавить параметры и валидировать их.

Пример эндпоинта, принимающего параметр count для указания количества постов:

add_action('rest_api_init', function () {
    register_rest_route('wpcoding/v1', '/posts', array(
        'methods' => 'GET',
        'callback' => 'wpcoding_get_posts_with_count',
        'permission_callback' => '__return_true',
        'args' => array(
            'count' => array(
                'required' => false,
                'default' => 5,
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param) && $param > 0 && $param <= 20;
                },
                'sanitize_callback' => 'absint',
            ),
        ),
    ));
});

function wpcoding_get_posts_with_count($request) {
    $count = $request->get_param('count');
    $posts = get_posts(array(
        'numberposts' => $count,
        'post_status' => 'publish',
    ));
    $data = array();
    foreach ($posts as $post) {
        $data[] = array(
            'id' => $post->ID,
            'title' => get_the_title($post),
            'excerpt' => get_the_excerpt($post),
        );
    }
    return $data;
}

Здесь реализована валидация параметра count, который должен быть числом от 1 до 20. Если параметр не передан, используется значение по умолчанию — 5.

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

Custom REST API может принимать данные и создавать новые записи или другие объекты. Например, создадим эндпоинт, который принимает POST-запрос с заголовком и содержимым для создания нового поста.

add_action('rest_api_init', function () {
    register_rest_route('wpcoding/v1', '/create-post', array(
        'methods' => 'POST',
        'callback' => 'wpcoding_create_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 wpcoding_create_post($request) {
    $params = $request->get_params();
    $post_data = array(
        'post_title' => $params['title'],
        'post_content' => $params['content'],
        'post_status' => 'draft',
        'post_author' => get_current_user_id(),
    );
    $post_id = wp_insert_post($post_data);
    if (is_wp_error($post_id)) {
        return new WP_Error('post_creation_failed', 'Не удалось создать запись', array('status' => 500));
    }
    return array('post_id' => $post_id, 'message' => 'Запись успешно создана');
}

Важный момент — разрешения. В примере используется permission_callback, который проверяет, что пользователь может редактировать посты. Это защищает API от неавторизованных вызовов.

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

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

WP REST API Controller — позволяет управлять стандартными эндпоинтами и создавать новые маршруты через интерфейс.
Advanced Custom Fields (ACF) — с помощью дополнения ACF to REST API можно автоматически добавить пользовательские поля в ответ API.
REST API Log — полезен для отладки и мониторинга запросов к REST API.

Эти инструменты не заменят программирование, но значительно ускорят процесс разработки и тестирования.

Обработка ошибок и стандарты ответов в Custom REST API

При разработке API важно правильно обрабатывать ошибки и возвращать понятные сообщения. WordPress предоставляет для этого класс WP_Error.

Пример возврата ошибки при неудачной валидации:

if (empty($params['title'])) {
    return new WP_Error('missing_title', 'Поле заголовка обязательно', array('status' => 400));
}

Статусы HTTP также важны. Для успешных ответов обычно используется 200, для ошибок валидации — 400, для ошибок сервера — 500 и т.д. Это помогает клиентам API корректно обрабатывать ответы.

Советы по безопасности при создании Custom REST API

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

Проверяйте права пользователя в permission_callback. Никогда не разрешайте неавторизованный доступ к критичным операциям.
Используйте санитайзеры и валидацию данных. Это защитит от XSS и SQL-инъекций.
Ограничивайте количество данных в ответах и запросах. Это поможет избежать DDoS и утечек информации.
Используйте nonce и другие механизмы защиты, если API вызывается из фронтенда.

Как создать Custom REST API в WordPress