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

WordPress с версии 4.7 имеет встроенный REST API, который позволяет создавать, получать, обновлять и удалять данные сайта через HTTP-запросы. Но что делать, если стандартных эндпоинтов недостаточно? В этой статье мы подробно рассмотрим, как создать собственный REST API endpoint в WordPress под ваши задачи.

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

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

Рассмотрим конкретный кейс: вам нужно предоставить внешний доступ к пользовательским задачам (tasks), которые хранятся в кастомном типе записи. Создадим endpoint, который вернет список задач в формате JSON и позволит добавлять новые задачи.

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

Для регистрации endpoint в WordPress используется функция register_rest_route(). Она принимает три параметра: пространство имен (namespace), путь (route) и массив с настройками — методами запроса, callback-функцией, правами доступа.

Добавим код в файл functions.php вашей темы или в отдельный плагин:

function wptasks_register_tasks_endpoint() {
    register_rest_route('wptasks/v1', '/tasks', array(
        'methods' => 'GET',
        'callback' => 'wptasks_get_tasks',
        'permission_callback' => function () {
            return current_user_can('read');
        },
    ));

    register_rest_route('wptasks/v1', '/tasks', array(
        'methods' => 'POST',
        'callback' => 'wptasks_create_task',
        'permission_callback' => function () {
            return current_user_can('edit_posts');
        },
        'args' => array(
            'title' => array(
                'required' => true,
                'type' => 'string',
                'sanitize_callback' => 'sanitize_text_field',
            ),
            'content' => array(
                'required' => false,
                'type' => 'string',
                'sanitize_callback' => 'sanitize_textarea_field',
            ),
        ),
    ));
}
add_action('rest_api_init', 'wptasks_register_tasks_endpoint');

Здесь мы зарегистрировали два endpoint для GET и POST запросов по URL /wp-json/wptasks/v1/tasks. GET вернет список задач, POST — создаст новую.

Реализация callback-функций для обработки запросов

Получение списка задач

Создадим функцию wptasks_get_tasks, которая вернет массив задач из кастомного типа записи task:

function wptasks_get_tasks(WP_REST_Request $request) {
    $args = array(
        'post_type' => 'task',
        'post_status' => 'publish',
        'numberposts' => 10,
    );
    $tasks = get_posts($args);
    $data = array();
    foreach ($tasks as $task) {
        $data[] = array(
            'id' => $task->ID,
            'title' => $task->post_title,
            'content' => $task->post_content,
        );
    }
    return rest_ensure_response($data);
}

Создание новой задачи

Функция wptasks_create_task принимает параметры из POST-запроса и создает новую запись:

function wptasks_create_task(WP_REST_Request $request) {
    $title = $request->get_param('title');
    $content = $request->get_param('content');

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

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

    return rest_ensure_response(array('id' => $post_id, 'message' => 'Задача успешно создана'));
}

Настройка прав доступа и безопасность REST API

Очень важно правильно настроить permission_callback, чтобы предотвратить несанкционированный доступ. В нашем примере для GET-запроса достаточно права read, а для создания задачи — права edit_posts, что соответствует ролям автора и выше.

Если вы хотите сделать публичный endpoint, можно возвращать true в permission_callback, но это не рекомендуется для операций записи.

Тестирование собственного REST API endpoint

Для проверки работы созданных endpoint используйте инструменты типа Postman или curl. Пример GET-запроса:

curl -X GET https://wptasks.ru/wp-json/wptasks/v1/tasks

Пример POST-запроса для создания задачи (требуется авторизация):

curl -X POST https://wptasks.ru/wp-json/wptasks/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"title":"Новая задача","content":"Описание задачи"}'

Расширение функционала собственного REST API

Вы можете добавить дополнительные методы (PUT, DELETE) для редактирования и удаления задач, добавить параметры фильтрации и пагинации, интегрировать с пользовательскими мета-полями.

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

Для примера добавим фильтр по статусу задачи через GET-параметр:

function wptasks_get_tasks(WP_REST_Request $request) {
    $status = $request->get_param('status') ?: 'publish';
    $args = array(
        'post_type' => 'task',
        'post_status' => $status,
        'numberposts' => 10,
    );
    $tasks = get_posts($args);
    // ... остальной код без изменений
}

Заключение

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