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

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

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

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

Создавая собственный endpoint, вы получаете гибкий инструмент для:

• Интеграции с внешними приложениями и сервисами.
• Создания одностраничных приложений (SPA).
• Разработки мобильных приложений, использующих данные сайта.
• Автоматизации бизнес-процессов через API.

Давайте разберёмся, как это сделать на практике.

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

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

add_action('rest_api_init', 'wpclass_register_custom_endpoint');
function wpclass_register_custom_endpoint() {
    register_rest_route('wpclass/v1', '/data', array(
        'methods' => 'GET',
        'callback' => 'wpclass_handle_custom_endpoint',
    ));
}

Здесь мы регистрируем маршрут /wp-json/wpclass/v1/data, который обрабатывает GET-запросы и вызывает функцию wpclass_handle_custom_endpoint.

Обработка запроса: пример callback-функции

Функция обратного вызова должна принимать объект WP_REST_Request и возвращать данные или объект WP_REST_Response. Пример простой функции, которая возвращает массив с сообщением:

function wpclass_handle_custom_endpoint(WP_REST_Request $request) {
    $response_data = array(
        'message' => 'Привет от wpclass! REST API endpoint работает.',
        'timestamp' => current_time('mysql')
    );
    return rest_ensure_response($response_data);
}

Таким образом, при обращении к нашему endpoint вы получите JSON с сообщением и текущим временем.

Как принимать параметры и работать с ними

REST API позволяет обрабатывать параметры, передаваемые в URL или теле запроса. Их можно получить из объекта WP_REST_Request с помощью методов get_param, get_query_params, get_body_params и других.

Например, расширим наш endpoint, чтобы принимать параметр id:

add_action('rest_api_init', 'wpclass_register_custom_endpoint_with_params');
function wpclass_register_custom_endpoint_with_params() {
    register_rest_route('wpclass/v1', '/item/(?P<id>\d+)', array(
        'methods' => 'GET',
        'callback' => 'wpclass_handle_custom_endpoint_with_params',
        'args' => array(
            'id' => array(
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param);
                }
            ),
        ),
    ));
}

function wpclass_handle_custom_endpoint_with_params(WP_REST_Request $request) {
    $id = $request->get_param('id');
    // Здесь можно получить данные по $id, например, пост
    $post = get_post($id);
    if (!$post) {
        return new WP_Error('no_post', 'Пост не найден', array('status' => 404));
    }

    return rest_ensure_response(array(
        'id' => $post->ID,
        'title' => $post->post_title,
        'content' => $post->post_content
    ));
}

Теперь запрос /wp-json/wpclass/v1/item/10 вернёт данные поста с ID 10.

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

Очень важно контролировать, кто и что может сделать через API. Для этого в массиве аргументов register_rest_route есть параметр permission_callback, который должен возвращать true или false, определяя доступ.

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

register_rest_route('wpclass/v1', '/private-data', array(
    'methods' => 'GET',
    'callback' => 'wpclass_private_data_callback',
    'permission_callback' => function() {
        return is_user_logged_in();
    }
));

function wpclass_private_data_callback() {
    return rest_ensure_response(array('secret' => 'Это закрытые данные!'));
}

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

Примеры полезных кастомных REST API endpoint

1. Получение списка кастомных записей

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

register_rest_route('wpclass/v1', '/books', array(
    'methods' => 'GET',
    'callback' => 'wpclass_get_books',
));

function wpclass_get_books() {
    $args = array(
        'post_type' => 'book',
        'posts_per_page' => 10
    );
    $query = new WP_Query($args);
    $books = array();
    foreach ($query->posts as $post) {
        $books[] = array(
            'id' => $post->ID,
            'title' => $post->post_title
        );
    }
    return rest_ensure_response($books);
}

2. Создание нового поста через API

Можно позволить создавать записи через POST-запрос, например:

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

function wpclass_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('missing_data', 'Заголовок и контент обязательны', array('status' => 400));
    }

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

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

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

Обзор полезных плагинов для расширения REST API

Если хочется минимизировать код и использовать готовые решения, рассмотрите эти плагины:

• WP REST API Controller — управляет доступом и полями для стандартных и кастомных типов записей.
• Advanced Custom Fields (ACF) to REST API — добавляет поддержку полей ACF в REST API.
• JWT Authentication for WP REST API — добавляет аутентификацию по JWT токенам, что удобно для безопасного доступа из внешних приложений.

Эти плагины облегчают настройку и расширение REST API без глубокого программирования.

Рекомендации по отладке и тестированию собственного endpoint

Для проверки работы API удобно использовать инструменты:

• Postman — графический клиент для отправки запросов с параметрами и заголовками.
• curl — командная строка, например:
  curl -X GET https://your-site.ru/wp-json/wpclass/v1/data
• Встроенный браузерный доступ к URL — для GET-запросов.

Если запросы не работают, проверьте:

• Правильность регистрации маршрута и callback-функции.
• Ошибка в коде PHP (включите WP_DEBUG).
• Настройки пермалинков (сбросьте в админке).
• Права доступа и авторизацию.

Итог

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