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

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

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

WordPress из коробки предоставляет большое количество REST API эндпоинтов для работы с постами, пользователями, таксономиями и т.д. Однако часто возникает задача добавить свой собственный API, который будет отдавать уникальные данные или выполнять специальные действия.

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

В следующих разделах мы рассмотрим, как это сделать на практике с примерами кода, которые легко адаптировать для ваших проектов.

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

Чтобы добавить свой endpoint, используйте хук rest_api_init, который вызывается при инициализации REST API. В этом хуке нужно вызвать функцию register_rest_route(), которая и регистрирует маршрут.

Вот базовый пример для сайта wpstart.ru, где мы создадим endpoint для получения списка последних 5 постов с кастомным форматом ответа:

add_action('rest_api_init', 'wpstart_register_custom_endpoint');
function wpstart_register_custom_endpoint() {
    register_rest_route('wpstart/v1', '/latest-posts/', array(
        'methods' => 'GET',
        'callback' => 'wpstart_get_latest_posts',
        'permission_callback' => '__return_true', // открытый доступ
    ));
}

function wpstart_get_latest_posts(WP_REST_Request $request) {
    $args = array(
        'numberposts' => 5,
        'post_status' => 'publish',
    );
    $posts = get_posts($args);
    $data = array();

    foreach ($posts as $post) {
        $data[] = array(
            'id' => $post->ID,
            'title' => $post->post_title,
            'date' => $post->post_date,
            'link' => get_permalink($post->ID),
        );
    }

    return rest_ensure_response($data);
}

В этом коде мы создали маршрут /wp-json/wpstart/v1/latest-posts/, который возвращает массив из 5 последних постов.

Подробное описание параметров register_rest_route

Функция register_rest_route() принимает три параметра:

• namespace — пространство имён, например, wpstart/v1. Это поможет избежать конфликтов с другими плагинами.
• route — собственно URL маршрута, например, /latest-posts/.
• args — массив аргументов, где нужно указать методы HTTP, callback для обработки запроса и опционально permission_callback для проверки прав.

Обратите внимание на permission_callback. Если его не указать, доступ к эндпоинту будет запрещён. В примере мы используем __return_true, чтобы сделать endpoint полностью открытым.

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

Ваш endpoint может принимать параметры запроса. Для их получения используйте объект WP_REST_Request. Вот пример, когда мы разрешаем клиенту задать количество постов через GET-параметр count:

function wpstart_get_latest_posts(WP_REST_Request $request) {
    $count = (int) $request->get_param('count');
    if ($count <= 0 || $count > 20) {
        $count = 5; // ограничиваем по умолчанию
    }

    $args = array(
        'numberposts' => $count,
        'post_status' => 'publish',
    );
    $posts = get_posts($args);
    $data = array();

    foreach ($posts as $post) {
        $data[] = array(
            'id' => $post->ID,
            'title' => $post->post_title,
            'date' => $post->post_date,
            'link' => get_permalink($post->ID),
        );
    }

    return rest_ensure_response($data);
}

Теперь запрос /wp-json/wpstart/v1/latest-posts?count=10 вернет 10 постов.

Добавление проверки прав доступа к вашему endpoint

Очень важно контролировать, кто может обращаться к вашему API. Для этого используйте permission_callback. Например, если endpoint должен быть доступен только залогиненным пользователям, используйте такую проверку:

function wpstart_permission_check() {
    return is_user_logged_in();
}

add_action('rest_api_init', function () {
    register_rest_route('wpstart/v1', '/private-data/', array(
        'methods' => 'GET',
        'callback' => 'wpstart_get_private_data',
        'permission_callback' => 'wpstart_permission_check',
    ));
});

Если пользователь не авторизован, WordPress автоматически вернет ошибку 401 Unauthorized.

Пример POST запроса и обработка данных в вашем REST API

REST API позволяет не только получать данные, но и отправлять их на сервер. Ниже пример создания поста через кастомный endpoint:

add_action('rest_api_init', function () {
    register_rest_route('wpstart/v1', '/create-post/', array(
        'methods' => 'POST',
        'callback' => 'wpstart_create_post',
        'permission_callback' => function() {
            return current_user_can('edit_posts');
        }
    ));
});

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

    if (empty($title) || empty($content)) {
        return new WP_Error('empty_data', 'Title and content are required', array('status' => 400));
    }

    $post_id = wp_insert_post(array(
        'post_title' => $title,
        'post_content' => $content,
        'post_status' => 'draft',
        'post_author' => get_current_user_id(),
    ));

    if (is_wp_error($post_id)) {
        return $post_id;
    }

    return rest_ensure_response(array('post_id' => $post_id));
}

Этот endpoint /wp-json/wpstart/v1/create-post/ позволяет авторизованным пользователям с правами редактирования создавать новые черновики.

Тестирование вашего кастомного REST API

Для тестирования API удобно использовать инструменты типа Postman или curl. Например, чтобы получить последние посты через curl, выполните:

curl https://wpstart.ru/wp-json/wpstart/v1/latest-posts/

Для POST запроса с созданием поста через curl:

curl -X POST https://wpstart.ru/wp-json/wpstart/v1/create-post/ \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "Новый пост", "content": "Содержимое поста"}'

Не забудьте заменить YOUR_TOKEN на действительный JWT или другой способ аутентификации.

Безопасность и лучшие практики при работе с REST API в WordPress

При создании REST API endpoints обязательно:

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

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