WP REST API: варианты ответа и их использование в WordPress

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

Основные форматы ответа WP REST API

По умолчанию, WP REST API возвращает данные в формате JSON с кодом ответа HTTP 200. Но в зависимости от задачи, можно возвращать разные типы ответов:

  • WP_REST_Response — стандартный объект ответа с данными и метаданными;
  • WP_Error — объект ошибки для возвращения сообщения об ошибке с HTTP кодом;
  • Массив или объект — простые данные, которые WP автоматически сериализует в JSON;
  • Произвольный объект — например, экземпляр класса, который поддерживает JSON сериализацию.

Давайте рассмотрим их подробнее с примерами кода.

Использование WP_REST_Response для настройки ответа

Класс WP_REST_Response позволяет задать не только тело ответа, но и HTTP-заголовки, статус и коды кеширования. Это гибкий способ сформировать ответ на запрос.

function wpapi_restapi_v2_custom_response(\WP_REST_Request $request) {
    $data = [
        'message' => 'Привет от WPAPI',
        'timestamp' => time()
    ];
    $response = new WP_REST_Response($data, 200);
    // Добавим заголовок
    $response->header('X-WPAPI-Version', 'v2');
    return $response;
}

В данном примере мы возвращаем массив с сообщением и текущим временем, устанавливаем статус 200 и добавляем кастомный HTTP-заголовок. Такой ответ легче расширять и контролировать.

Настройка кеширования и заголовков

WP_REST_Response позволяет задать заголовки, влияющие на кеширование, что важно для производительности:

$response->set_headers([
    'Cache-Control' => 'max-age=3600, must-revalidate',
]);

Так вы укажете браузеру и прокси, что ответ можно кешировать 1 час.

Обработка ошибок с помощью WP_Error

Для возврата ошибок в REST API используется класс WP_Error. Он позволяет задать код ошибки, сообщение и дополнительные данные.

function wpapi_restapi_v2_error_example(\WP_REST_Request $request) {
    if (!$request->get_param('id')) {
        return new WP_Error(
            'wpapi_missing_id',
            'Параметр ID обязателен',
            ['status' => 400]
        );
    }
    // Логика при наличии параметра
}

Здесь при отсутствии обязательного параметра возвращается ошибка с кодом 400 (Bad Request). WP REST API автоматически преобразует этот объект в корректный JSON-ответ с нужным HTTP статусом.

Возврат простых массивов и объектов

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

function wpapi_restapi_v2_simple_response() {
    return [
        'success' => true,
        'data' => [1, 2, 3]
    ];
}

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

Пример регистрации эндпоинта с различными типами ответов

Объединим всё в одном примере:

add_action('rest_api_init', function () {
    register_rest_route('wpapi/v2', '/test-response/', [
        'methods' => 'GET',
        'callback' => 'wpapi_restapi_v2_test_response',
        'permission_callback' => '__return_true',
    ]);
});

function wpapi_restapi_v2_test_response(\WP_REST_Request $request) {
    $type = $request->get_param('type');

    switch ($type) {
        case 'response':
            $data = ['msg' => 'Это WP_REST_Response'];
            return new WP_REST_Response($data, 200);

        case 'error':
            return new WP_Error('wpapi_error', 'Произошла ошибка', ['status' => 500]);

        case 'array':
            return ['msg' => 'Простой массив'];

        default:
            return new WP_REST_Response(['msg' => 'По умолчанию'], 200);
    }
}

Можно проверить разные варианты, передав параметр type в URL.

Рекомендации по выбору типа ответа

При разработке REST API в WordPress придерживайтесь следующих рекомендаций:

  • Используйте WP_REST_Response, если нужно контролировать статус, заголовки или кеширование.
  • Возвращайте WP_Error для ошибок с корректными HTTP статусами.
  • Для простых данных можно возвращать массивы или объекты, если не требуется дополнительная настройка.
  • Обрабатывайте ошибки и исключения, чтобы не возвращать некорректные данные.

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

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

  • Clearfy Pro — оптимизация и безопасность API;
  • WPGPT — интеграция AI для автоматизации ответов;
  • WPRemark — расширенные возможности комментариев через API.

Эти инструменты помогут сделать ваш REST API более мощным и удобным.

Шаблоны для WP Плагины для WP