Как добавить поддержку REST API в своем плагине WordPress

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

Что такое REST API в WordPress и зачем его использовать

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

Добавляя собственные маршруты в REST API, вы можете:

• Создавать, читать, обновлять и удалять кастомные данные вашего плагина;
• Интегрировать WordPress с внешними приложениями, мобильными клиентами, фронтенд-фреймворками (React, Vue и т.д.);
• Обеспечить безопасный и стандартизированный API для взаимодействия с вашим функционалом.

Без REST API часто приходилось создавать собственные обработчики AJAX-запросов или использовать сложные методы передачи данных. REST API упрощает эти задачи и стандартизирует процесс.

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

Чтобы добавить новый маршрут, нужно подписаться на хук rest_api_init и зарегистрировать обработчик через функцию register_rest_route. Рассмотрим пример, который добавляет путь /wpdevelop/v1/hello и возвращает простое приветствие.

add_action('rest_api_init', 'wpdevelop_register_routes');

function wpdevelop_register_routes() {
    register_rest_route('wpdevelop/v1', '/hello', array(
        'methods' => 'GET',
        'callback' => 'wpdevelop_hello_callback',
        'permission_callback' => '__return_true',
    ));
}

function wpdevelop_hello_callback(WP_REST_Request $request) {
    return array('message' => 'Привет из WPDevelop!');
}

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

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

• namespace — пространство имен API, обычно в формате <название_плагина>/v1;
• route — путь маршрута;
• methods — HTTP методы, например GET, POST, PUT, DELETE;
• callback — функция, которая обрабатывает запрос и возвращает ответ;
• permission_callback — функция проверки прав доступа.

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

REST API позволяет принимать параметры из URL, тела запроса и заголовков. Для получения параметров используйте объект WP_REST_Request. Например, добавим в наш маршрут параметр name, который возвращаем в ответе.

function wpdevelop_hello_callback(WP_REST_Request $request) {
    $name = $request->get_param('name');
    if (empty($name)) {
        return new WP_Error('no_name', 'Имя не указано', array('status' => 400));
    }
    return array('message' => "Привет, $name!");
}

Для валидации параметров можно использовать ключ args в register_rest_route. Например:

register_rest_route('wpdevelop/v1', '/hello', array(
    'methods' => 'GET',
    'callback' => 'wpdevelop_hello_callback',
    'permission_callback' => '__return_true',
    'args' => array(
        'name' => array(
            'required' => true,
            'validate_callback' => function($param) {
                return is_string($param) && strlen($param) > 0;
            },
            'sanitize_callback' => 'sanitize_text_field',
        ),
    ),
));

Так мы гарантируем, что параметр name всегда будет непустой строкой, и сразу очищаем его.

Создание CRUD API для кастомного типа записей

Допустим, у вас в плагине есть кастомный тип записей wpdevelop_item. Реализуем базовые операции с ним через REST API: получение списка, создание, обновление и удаление.

Регистрация маршрутов

add_action('rest_api_init', 'wpdevelop_register_items_routes');

function wpdevelop_register_items_routes() {
    register_rest_route('wpdevelop/v1', '/items', array(
        'methods' => 'GET',
        'callback' => 'wpdevelop_get_items',
        'permission_callback' => '__return_true',
    ));

    register_rest_route('wpdevelop/v1', '/items', array(
        'methods' => 'POST',
        'callback' => 'wpdevelop_create_item',
        'permission_callback' => 'wpdevelop_permissions_check',
        'args' => array(
            'title' => array(
                'required' => true,
                'sanitize_callback' => 'sanitize_text_field',
            ),
            'content' => array(
                'required' => false,
                'sanitize_callback' => 'wp_kses_post',
            ),
        ),
    ));

    register_rest_route('wpdevelop/v1', '/items/(?P<id>\d+)', array(
        'methods' => 'PUT',
        'callback' => 'wpdevelop_update_item',
        'permission_callback' => 'wpdevelop_permissions_check',
        'args' => array(
            'id' => array('required' => true),
            'title' => array('required' => false, 'sanitize_callback' => 'sanitize_text_field'),
            'content' => array('required' => false, 'sanitize_callback' => 'wp_kses_post'),
        ),
    ));

    register_rest_route('wpdevelop/v1', '/items/(?P<id>\d+)', array(
        'methods' => 'DELETE',
        'callback' => 'wpdevelop_delete_item',
        'permission_callback' => 'wpdevelop_permissions_check',
        'args' => array('id' => array('required' => true)),
    ));
}

Реализация обработчиков

function wpdevelop_get_items(WP_REST_Request $request) {
    $args = array('post_type' => 'wpdevelop_item', 'posts_per_page' => 10);
    $query = new WP_Query($args);
    $items = array();
    foreach ($query->posts as $post) {
        $items[] = array(
            'id' => $post->ID,
            'title' => $post->post_title,
            'content' => $post->post_content,
        );
    }
    return $items;
}

function wpdevelop_create_item(WP_REST_Request $request) {
    $title = $request->get_param('title');
    $content = $request->get_param('content');
    $post_id = wp_insert_post(array(
        'post_type' => 'wpdevelop_item',
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => 'publish',
    ));
    if (is_wp_error($post_id)) {
        return $post_id;
    }
    return array('id' => $post_id, 'message' => 'Элемент создан');
}

function wpdevelop_update_item(WP_REST_Request $request) {
    $id = (int) $request->get_param('id');
    $post = get_post($id);
    if (!$post || $post->post_type !== 'wpdevelop_item') {
        return new WP_Error('invalid_id', 'Элемент не найден', array('status' => 404));
    }
    $data = array('ID' => $id);
    if ($title = $request->get_param('title')) {
        $data['post_title'] = $title;
    }
    if ($content = $request->get_param('content')) {
        $data['post_content'] = $content;
    }
    $updated = wp_update_post($data, true);
    if (is_wp_error($updated)) {
        return $updated;
    }
    return array('id' => $id, 'message' => 'Элемент обновлен');
}

function wpdevelop_delete_item(WP_REST_Request $request) {
    $id = (int) $request->get_param('id');
    $deleted = wp_delete_post($id, true);
    if (!$deleted) {
        return new WP_Error('delete_failed', 'Ошибка удаления', array('status' => 500));
    }
    return array('id' => $id, 'message' => 'Элемент удален');
}

function wpdevelop_permissions_check() {
    return current_user_can('edit_posts');
}

Обратите внимание, что для создания, обновления и удаления мы проверяем права пользователя через current_user_can('edit_posts'). Это базовая проверка, которую можно расширять.

Как тестировать и использовать собственный REST API

После добавления маршрутов вы можете проверить их, отправляя HTTP-запросы через:

• Postman или Insomnia — удобные GUI-инструменты для тестирования API;
• curl в терминале, например: curl https://example.com/wp-json/wpdevelop/v1/hello?name=Игорь;
• JavaScript-код на фронтенде с использованием fetch или axios;
• плагины для браузера, например RESTer.

Пример запроса с fetch:

fetch('/wp-json/wpdevelop/v1/items')
  .then(response => response.json())
  .then(data => console.log(data));

Использование плагина Clearfy Pro для оптимизации REST API

Если вы хотите контролировать доступность REST API и защитить сайт от нежелательных запросов, обратите внимание на плагин Clearfy Pro. Он позволяет гибко управлять REST API, отключать стандартные маршруты и защищать сайт от атак.

Такой контроль особенно полезен при добавлении собственных маршрутов — вы можете сделать их доступными только для определенных пользователей или IP.

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

При создании REST API важно:

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

Правильная реализация REST API позволяет создавать быстро работающие и безопасные интеграции.