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

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

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

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

Создание собственных REST API эндпоинтов позволяет:

создавать безопасный и стандартизированный интерфейс для внешних приложений;
упрощать интеграцию с мобильными приложениями и SPA;
организовывать кастомные действия и обработку данных;
избегать прямого доступа к базе данных и обеспечивать безопасность;
делать код более модульным и переиспользуемым.

Регистрация собственного REST API эндпоинта в WordPress

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

add_action('rest_api_init', 'wpbloger_register_api_routes');
function wpbloger_register_api_routes() {
    register_rest_route('wpbloger/v1', '/hello/', [
        'methods' => 'GET',
        'callback' => 'wpbloger_hello_callback',
        'permission_callback' => '__return_true', // Доступ открыт всем
    ]);
}

function wpbloger_hello_callback(WP_REST_Request $request) {
    return [
        'message' => 'Привет от wpbloger REST API!',
        'timestamp' => time()
    ];
}

В этом примере мы создаём маршрут /wp-json/wpbloger/v1/hello/, который при GET-запросе вернёт JSON с приветственным сообщением и текущим временем.

Пояснение параметров регистрации

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

Пример: создание REST API для кастомного пост-типа

Предположим, у вас есть кастомный пост-тип book. Нужно создать эндпоинт, который вернёт список книг с определённой категорией и дополнительными полями.

add_action('rest_api_init', 'wpbloger_register_books_endpoint');
function wpbloger_register_books_endpoint() {
    register_rest_route('wpbloger/v1', '/books/', [
        'methods' => 'GET',
        'callback' => 'wpbloger_get_books',
        'permission_callback' => '__return_true',
        'args' => [
            'category' => [
                'required' => false,
                'type' => 'string',
            ],
            'limit' => [
                'required' => false,
                'type' => 'integer',
                'default' => 10,
            ],
        ],
    ]);
}

function wpbloger_get_books(WP_REST_Request $request) {
    $category = $request->get_param('category');
    $limit = $request->get_param('limit');

    $args = [
        'post_type' => 'book',
        'posts_per_page' => $limit,
        'post_status' => 'publish',
    ];

    if ($category) {
        $args['tax_query'] = [
            [
                'taxonomy' => 'category',
                'field' => 'slug',
                'terms' => $category,
            ]
        ];
    }

    $query = new WP_Query($args);
    $books = [];

    while ($query->have_posts()) {
        $query->the_post();
        $books[] = [
            'id' => get_the_ID(),
            'title' => get_the_title(),
            'author' => get_post_meta(get_the_ID(), 'book_author', true),
            'published_year' => get_post_meta(get_the_ID(), 'published_year', true),
            'link' => get_permalink(),
        ];
    }
    wp_reset_postdata();

    return rest_ensure_response($books);
}

Этот эндпоинт поддерживает параметры category для фильтрации и limit для ограничения количества результатов. В ответе возвращается массив книг с основными метаданными.

Обработка POST-запросов и проверка прав доступа

Для записи или обновления данных через REST API нужно использовать метод POST (или PUT/PATCH). Важно реализовать проверку прав пользователя, чтобы защитить сайт от неавторизованных изменений.

add_action('rest_api_init', 'wpbloger_register_create_book');
function wpbloger_register_create_book() {
    register_rest_route('wpbloger/v1', '/books/', [
        'methods' => 'POST',
        'callback' => 'wpbloger_create_book',
        'permission_callback' => function () {
            return current_user_can('edit_posts');
        },
        'args' => [
            'title' => [
                'required' => true,
                'type' => 'string',
            ],
            'author' => [
                'required' => true,
                'type' => 'string',
            ],
            'published_year' => [
                'required' => false,
                'type' => 'integer',
            ],
        ],
    ]);
}

function wpbloger_create_book(WP_REST_Request $request) {
    $title = sanitize_text_field($request->get_param('title'));
    $author = sanitize_text_field($request->get_param('author'));
    $year = intval($request->get_param('published_year'));

    $post_id = wp_insert_post([
        'post_type' => 'book',
        'post_title' => $title,
        'post_status' => 'publish',
    ]);

    if (is_wp_error($post_id)) {
        return new WP_Error('cant-create', 'Не удалось создать книгу', ['status' => 500]);
    }

    update_post_meta($post_id, 'book_author', $author);
    if ($year) {
        update_post_meta($post_id, 'published_year', $year);
    }

    return rest_ensure_response(['success' => true, 'id' => $post_id]);
}

Здесь мы создаём эндпоинт для добавления новой книги. Для доступа необходима роль с возможностью edit_posts. Все входные данные проходят базовую очистку.

Отладка и тестирование REST API эндпоинтов

Для тестирования эндпоинтов удобно использовать инструменты Postman, Insomnia или даже браузер (для GET-запросов). Важные моменты при отладке:

Проверяйте правильность namespace и пути.
Используйте permission_callback для контроля доступа.
Возвращайте данные через rest_ensure_response для совместимости.
Обрабатывайте ошибки с помощью WP_Error.
Логируйте запросы и ответы при необходимости.

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

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

Clearfy Pro — помогает оптимизировать и обезопасить REST API, отключая ненужные эндпоинты и настраивая права доступа.
WPRemark — расширяет возможности комментариев через REST API.

Итог

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