Как создать функциональный REST API endpoint в WordPress для обмена данными

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

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

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

Примеры применения собственного REST API endpoint:

• Обмен данными с мобильным приложением
• Получение и отправка специализированной информации, не попадающей в стандартные типы записей
• Интеграция с внешними сервисами и CRM
• Создание интерфейса для AJAX-запросов без использования admin-ajax.php

Создание собственного endpoint в WordPress реализуется через регистрацию маршрута и обработчика запроса.

Регистрация REST API endpoint: базовый пример

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

add_action('rest_api_init', 'wptemplates_register_custom_endpoint');
function wptemplates_register_custom_endpoint() {
    register_rest_route('wptemplates/v1', '/latest-products/', array(
        'methods' => 'GET',
        'callback' => 'wptemplates_get_latest_products',
        'permission_callback' => '__return_true',
    ));
}

function wptemplates_get_latest_products($request) {
    $args = array(
        'post_type' => 'product',
        'posts_per_page' => 5,
        'post_status' => 'publish',
    );
    $query = new WP_Query($args);
    $products = array();

    while ($query->have_posts()) {
        $query->the_post();
        $products[] = array(
            'id' => get_the_ID(),
            'title' => get_the_title(),
            'link' => get_permalink(),
        );
    }
    wp_reset_postdata();

    return rest_ensure_response($products);
}

В этом коде мы регистрируем маршрут /wp-json/wptemplates/v1/latest-products/, который при GET-запросе возвращает массив из 5 последних продуктов. Параметр permission_callback здесь возвращает true, то есть endpoint доступен всем, но в рабочем проекте желательно добавлять проверку прав доступа.

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

Часто API требует передачи параметров, например, пагинации, фильтров или поиска. В register_rest_route() можно указать схему аргументов, их типы и валидаторы.

Добавим параметр category для фильтрации продуктов по таксономии "product_cat":

register_rest_route('wptemplates/v1', '/products/', array(
    'methods' => 'GET',
    'callback' => 'wptemplates_get_products_by_category',
    'permission_callback' => '__return_true',
    'args' => array(
        'category' => array(
            'required' => false,
            'validate_callback' => function($param, $request, $key) {
                return is_string($param);
            },
        ),
    ),
));

function wptemplates_get_products_by_category(WP_REST_Request $request) {
    $category = $request->get_param('category');
    
    $tax_query = array();
    if ($category) {
        $tax_query[] = array(
            'taxonomy' => 'product_cat',
            'field'    => 'slug',
            'terms'    => $category,
        );
    }

    $args = array(
        'post_type' => 'product',
        'posts_per_page' => 10,
        'post_status' => 'publish',
        'tax_query' => $tax_query,
    );

    $query = new WP_Query($args);
    $products = array();

    while ($query->have_posts()) {
        $query->the_post();
        $products[] = array(
            'id' => get_the_ID(),
            'title' => get_the_title(),
        );
    }
    wp_reset_postdata();

    return rest_ensure_response($products);
}

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

Добавление POST-запросов и безопасность

Для создания или обновления данных через REST API используются POST, PUT или PATCH запросы. В таких случаях важно реализовать проверку nonce и прав пользователя.

Пример endpoint для создания новой записи типа "review" с проверкой прав:

add_action('rest_api_init', function () {
    register_rest_route('wptemplates/v1', '/add-review/', array(
        'methods' => 'POST',
        'callback' => 'wptemplates_add_review',
        'permission_callback' => 'wptemplates_check_permissions',
        'args' => array(
            'title' => array('required' => true),
            'content' => array('required' => true),
        ),
    ));
});

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

function wptemplates_add_review(WP_REST_Request $request) {
    $title = sanitize_text_field($request->get_param('title'));
    $content = sanitize_textarea_field($request->get_param('content'));

    $post_id = wp_insert_post(array(
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => 'pending',
        'post_type' => 'review',
    ));

    if (is_wp_error($post_id)) {
        return new WP_Error('cant-create', __('Не удалось создать отзыв'), array('status' => 500));
    }

    return rest_ensure_response(array('id' => $post_id, 'message' => 'Отзыв создан и ожидает модерации'));
}

В данном примере endpoint доступен только пользователям с правом edit_posts, что предотвращает несанкционированное создание записей.

Расширенные возможности: кастомные поля и метаданные

Часто требуется возвращать или принимать в API данные из пользовательских полей (метаданных). Для их обработки можно использовать функции get_post_meta() и update_post_meta().

Например, расширим GET-endpoint для продуктов, чтобы возвращать цену из метаполя _price:

function wptemplates_get_latest_products($request) {
    $args = array(
        'post_type' => 'product',
        'posts_per_page' => 5,
        'post_status' => 'publish',
    );
    $query = new WP_Query($args);
    $products = array();

    while ($query->have_posts()) {
        $query->the_post();
        $products[] = array(
            'id' => get_the_ID(),
            'title' => get_the_title(),
            'link' => get_permalink(),
            'price' => get_post_meta(get_the_ID(), '_price', true),
        );
    }
    wp_reset_postdata();

    return rest_ensure_response($products);
}

Это позволит клиентам API получать полную информацию о продукте, включая цену.

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

Для упрощения создания API и расширения функционала можно использовать готовые плагины:

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

Эти плагины помогут обезопасить API и добавить дополнительные возможности без необходимости писать весь код вручную.

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

Для тестирования собственного API удобно использовать инструменты, такие как Postman или встроенный в браузеры REST клиент. Важно проверять корректность формата данных, обработку ошибок и права доступа.

Также можно добавить логирование запросов и ответов, чтобы отслеживать работу endpoint в реальном времени.

Выводы и рекомендации по созданию REST API endpoint в WordPress

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

• Использовать встроенные хуки и функции WordPress для регистрации маршрутов.
• Обрабатывать и валидировать входящие параметры.
• Реализовывать проверку прав доступа и безопасность.
• Поддерживать стандартный формат ответов с помощью rest_ensure_response().
• Тестировать все сценарии работы API.

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