Как создать свое API в WordPress: подробное руководство с примерами кода

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

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

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

• Расширить функциональность сайта под конкретные нужды
• Отфильтровать данные и предоставить их в нужном формате
• Реализовать авторизацию и кастомную логику обработки данных

Далее рассмотрим, как это сделать на практике.

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

Основы регистрации маршрута

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

add_action('rest_api_init', 'wpexamples_register_custom_route');
function wpexamples_register_custom_route() {
    register_rest_route('wpexamples/v1', '/data', array(
        'methods'  => 'GET',
        'callback' => 'wpexamples_get_custom_data',
    ));
}

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

Реализация функции-обработчика

Функция-обработчик отвечает за формирование и возврат данных. Пример простого ответа с массивом данных:

function wpexamples_get_custom_data( WP_REST_Request $request ) {
    $data = array(
        'message' => 'Привет из собственного API!',
        'time'    => current_time('mysql'),
    );
    return rest_ensure_response($data);
}

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

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

Прием и проверка параметров

Чаще всего API должен принимать входные параметры. Например, возьмем параметр id для получения конкретного поста. Добавим аргумент args в регистрацию маршрута:

register_rest_route('wpexamples/v1', '/post/(?P<id>\d+)', array(
    'methods'  => 'GET',
    'callback' => 'wpexamples_get_post_by_id',
    'args'     => array(
        'id' => array(
            'validate_callback' => function($param, $request, $key) {
                return is_numeric($param) && $param > 0;
            }
        ),
    ),
));

В этом примере маршрут принимает числовой параметр id через URL, например, /wp-json/wpexamples/v1/post/15.

Обработка запроса с параметром

function wpexamples_get_post_by_id( WP_REST_Request $request ) {
    $id = (int) $request->get_param('id');
    $post = get_post($id);

    if (empty($post) || $post->post_status !== 'publish') {
        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,
        'date'    => $post->post_date,
    ));
}

Если пост не найден или не опубликован, возвращаем ошибку с соответствующим HTTP статусом.

Авторизация и права доступа в собственном API

Ограничение доступа

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

register_rest_route('wpexamples/v1', '/secure-data', array(
    'methods'  => 'GET',
    'callback' => 'wpexamples_get_secure_data',
    'permission_callback' => function() {
        return is_user_logged_in();
    },
));

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

Пример защищенного обработчика

function wpexamples_get_secure_data( WP_REST_Request $request ) {
    $current_user = wp_get_current_user();
    return rest_ensure_response(array(
        'user_id'   => $current_user->ID,
        'user_name' => $current_user->user_login,
        'message'   => 'Доступ разрешен',
    ));
}

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

Чтобы расширить возможности собственного API, можно использовать такие плагины:

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

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

Как тестировать собственные API эндпоинты

Использование Postman и curl

Для проверки работы созданных маршрутов удобно использовать Postman — графический клиент для отправки HTTP-запросов. Также можно воспользоваться командной строкой:

curl -X GET https://ваш-сайт.ru/wp-json/wpexamples/v1/data

Если маршрут требует авторизации, нужно передавать соответствующие заголовки, например, cookie сессии или токен.

Отладка и логирование запросов

Для отслеживания ошибок и запросов полезно добавить логирование. Пример простого логера в функцию обработчик:

function wpexamples_log_request( $message ) {
    if ( defined('WP_DEBUG') && WP_DEBUG ) {
        error_log('[wpexamples-api] ' . $message);
    }
}

Вызывайте wpexamples_log_request('Описание события') в ключевых местах.

Расширяемость и лучшие практики при создании API в WordPress

Использование классов и ООП

Для более сложных проектов рекомендуем оформлять API в виде класса, что улучшит структуру и тестируемость кода:

class WPExamples_API {
    public function __construct() {
        add_action('rest_api_init', array($this, 'register_routes'));
    }

    public function register_routes() {
        register_rest_route('wpexamples/v1', '/example', array(
            'methods'  => 'GET',
            'callback' => array($this, 'handle_example'),
        ));
    }

    public function handle_example( WP_REST_Request $request ) {
        return rest_ensure_response(array('message' => 'Пример ООП API'));
    }
}
new WPExamples_API();

Кэширование и оптимизация

Для снижения нагрузки на сервер используйте кэширование ответов, например, с помощью Transients API или внешних решений. Кэшируйте данные, которые редко меняются.

Документирование API

Важно поддерживать документацию для вашего API, чтобы другие разработчики понимали, как им пользоваться. Для этого можно использовать плагины или автоматически генерировать OpenAPI спецификации.