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

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

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

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

В этой статье мы подробно разберём, как создать собственный REST API endpoint в WordPress, зарегистрировать маршрут, обработать запрос и вернуть данные в формате JSON.

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

Для регистрации собственного endpoint используется хук rest_api_init и функция register_rest_route. Рассмотрим простой пример, который создаст endpoint, доступный по адресу /wp-json/wp5/v1/hello.

add_action('rest_api_init', 'wp5_register_hello_endpoint');
function wp5_register_hello_endpoint() {
    register_rest_route('wp5/v1', '/hello', array(
        'methods' => 'GET',
        'callback' => 'wp5_handle_hello_endpoint',
        'permission_callback' => '__return_true', // разрешаем доступ всем
    ));
}

function wp5_handle_hello_endpoint(WP_REST_Request $request) {
    return array('message' => 'Привет из собственного REST API endpoint!');
}

Этот код можно поместить в файл плагина или в functions.php активной темы. Теперь при обращении по адресу https://ваш-сайт/wp-json/wp5/v1/hello вы получите JSON с сообщением.

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

Первый параметр — пространство имён (namespace), здесь wp5/v1. Это помогает структурировать маршруты и версионировать API.

Второй — путь маршрута, в нашем случае /hello.

В параметрах указываем HTTP-методы, которые поддерживает маршрут (GET, POST, PUT и т.д.), функцию обратного вызова для обработки запроса и функцию проверки прав доступа.

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

Часто endpoint должен принимать параметры, например, ID записи или фильтры. Рассмотрим пример, где в запросе GET принимается параметр name, и возвращается персональное приветствие.

add_action('rest_api_init', 'wp5_register_greet_endpoint');
function wp5_register_greet_endpoint() {
    register_rest_route('wp5/v1', '/greet/', array(
        'methods' => 'GET',
        'callback' => 'wp5_handle_greet_endpoint',
        'permission_callback' => '__return_true',
        'args' => array(
            'name' => array(
                'required' => false,
                'validate_callback' => function($param) {
                    return is_string($param) && !empty($param);
                },
            ),
        ),
    ));
}

function wp5_handle_greet_endpoint(WP_REST_Request $request) {
    $name = $request->get_param('name');
    if (!$name) {
        $name = 'Гость';
    }
    return array('message' => "Привет, $name!");
}

Теперь, вызвав https://ваш-сайт/wp-json/wp5/v1/greet?name=Иван, вы получите ответ {"message":"Привет, Иван!"}.

Защита REST API endpoint и проверка прав доступа

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

В параметре permission_callback вы можете указать функцию, которая проверит текущего пользователя или токен авторизации. Например, разрешить доступ только авторизованным пользователям:

function wp5_permission_check() {
    return is_user_logged_in();
}

И в регистрации маршрута:

'permission_callback' => 'wp5_permission_check'

Также можно проверить конкретные права доступа (capabilities), например:

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

Это гарантирует, что endpoint будет доступен только редакторам и администраторам.

Пример: создание endpoint для получения списка пользовательских записей

Рассмотрим более полезный пример — endpoint, который возвращает все записи определённого пользовательского типа, например, 'product', с пагинацией и фильтрацией по метаданным.

add_action('rest_api_init', 'wp5_register_products_endpoint');
function wp5_register_products_endpoint() {
    register_rest_route('wp5/v1', '/products/', array(
        'methods' => 'GET',
        'callback' => 'wp5_get_products',
        'permission_callback' => '__return_true',
        'args' => array(
            'page' => array(
                'required' => false,
                'default' => 1,
                'validate_callback' => 'is_numeric',
            ),
            'per_page' => array(
                'required' => false,
                'default' => 10,
                'validate_callback' => 'is_numeric',
            ),
            'price_min' => array(
                'required' => false,
                'validate_callback' => 'is_numeric',
            ),
            'price_max' => array(
                'required' => false,
                'validate_callback' => 'is_numeric',
            ),
        ),
    ));
}

function wp5_get_products(WP_REST_Request $request) {
    $page = (int)$request->get_param('page');
    $per_page = (int)$request->get_param('per_page');
    $price_min = $request->get_param('price_min');
    $price_max = $request->get_param('price_max');

    $meta_query = array('relation' => 'AND');
    if ($price_min !== null) {
        $meta_query[] = array(
            'key' => 'price',
            'value' => $price_min,
            'compare' => '>=',
            'type' => 'NUMERIC',
        );
    }
    if ($price_max !== null) {
        $meta_query[] = array(
            'key' => 'price',
            'value' => $price_max,
            'compare' => '<=',
            'type' => 'NUMERIC',
        );
    }

    $query_args = array(
        'post_type' => 'product',
        'posts_per_page' => $per_page,
        'paged' => $page,
        'meta_query' => $meta_query,
    );

    $query = new WP_Query($query_args);
    $items = array();
    foreach ($query->posts as $post) {
        $items[] = array(
            'id' => $post->ID,
            'title' => get_the_title($post),
            'price' => get_post_meta($post->ID, 'price', true),
            'link' => get_permalink($post),
        );
    }

    return array(
        'page' => $page,
        'per_page' => $per_page,
        'total' => (int)$query->found_posts,
        'items' => $items,
    );
}

Такой endpoint позволит получить список товаров с возможностью фильтрации по цене и пагинацией, что удобно для фронтенд-приложений.

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

Разработка REST API проще с помощью специализированных инструментов:

• WP REST API Controller — плагин для управления разрешениями и настройками стандартных endpoint.
• Postman — внешнее приложение для тестирования HTTP-запросов к вашему API.
• Debug Bar REST API — плагин для отладки REST API запросов внутри админки WordPress.

Используйте их для удобного тестирования и отладки собственных endpoint.

Итоги и рекомендации по созданию REST API endpoint

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

• Правильно регистрировать маршруты и обрабатывать параметры.
• Обеспечивать безопасность и проверять права доступа.
• Возвращать данные в стандартизированном формате и с понятной структурой.
• Тестировать и документировать API.

Следуя этим рекомендациям и примерам, вы сможете создавать гибкие и надёжные решения для ваших проектов на WordPress.