Как изменить код ответа REST API в WordPress для кастомных запросов

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

Понимание HTTP-кодов ответа в WordPress REST API

REST API возвращает объект WP_REST_Response, который содержит тело ответа и HTTP-статус. Стандартные коды — 200 (успех), 404 (не найдено), 500 (ошибка сервера) и т.д. — помогают клиенту понять результат запроса.

Однако иногда требуется вернуть нестандартный код, например 202 (принято, но обработка идет), 403 (доступ запрещен), 422 (неверные данные) или кастомные статусы для специфичных бизнес-логик.

По умолчанию функции-обработчики REST API возвращают массивы или объекты, которые WordPress оборачивает в WP_REST_Response с кодом 200. Чтобы изменить код, нужно явно создать объект ответа и задать статус.

Создание кастомного REST API эндпоинта с измененным кодом ответа

Пример простого кастомного эндпоинта, который возвращает HTTP статус 202:

add_action('rest_api_init', function () {
    register_rest_route('wpcompany/v1', '/custom-response', [
        'methods' => 'GET',
        'callback' => 'wpcompany_custom_response_callback',
        'permission_callback' => '__return_true',
    ]);
});

function wpcompany_custom_response_callback(WP_REST_Request $request) {
    $data = [
        'message' => 'Запрос принят, обработка продолжается',
        'status' => 'processing'
    ];
    $response = new WP_REST_Response($data);
    $response->set_status(202); // Устанавливаем код ответа 202 Accepted
    return $response;
}

В этом примере клиент, сделав запрос к /wp-json/wpcompany/v1/custom-response, получит HTTP/1.1 202 и JSON с сообщением.

Почему важно менять код ответа

Клиенты, особенно фронтенд-приложения и мобильные приложения, полагаются на коды ответа для обработки результатов. Если всегда возвращать 200, даже при ошибках или отложенной обработке, клиент может неправильно интерпретировать состояние.

Например, код 422 (Unprocessable Entity) поможет указать, что данные не прошли валидацию, а не просто успешный ответ с ошибкой внутри JSON.

Изменение кода ответа для стандартных эндпоинтов WordPress REST API

Иногда нужно изменить код ответа для существующих маршрутов, например, при ошибках авторизации или валидации. Для этого используется фильтр rest_post_dispatch, который позволяет подменить объект ответа перед отправкой клиенту.

Пример изменения кода ответа 401 на 403 для маршрута получения постов:

add_filter('rest_post_dispatch', 'wpcompany_modify_rest_response_status', 10, 3);

function wpcompany_modify_rest_response_status($response, $server, $request) {
    if ($request->get_route() === '/wp/v2/posts' && $response instanceof WP_REST_Response) {
        if ($response->get_status() === 401) {
            $response->set_status(403);
        }
    }
    return $response;
}

Этот код проверяет, что маршрут — получение постов, и если код 401 (неавторизован), заменяет его на 403 (доступ запрещен). Это может быть полезно для различных требований безопасности или API-стандартизации.

Обработка ошибок с кастомными кодами и сообщениями

Для генерации ошибок с нужным HTTP-статусом можно использовать класс WP_Error в связке с WP_REST_Response. Это позволяет задать код и детализированное сообщение.

Пример возврата ошибки с кодом 422:

function wpcompany_validate_request(WP_REST_Request $request) {
    $param = $request->get_param('data');
    if (empty($param)) {
        $error = new WP_Error(
            'wpcompany_missing_data',
            'Параметр data обязателен',
            ['status' => 422]
        );
        return rest_ensure_response($error);
    }
    return ['success' => true];
}

Зарегистрируем маршрут:

add_action('rest_api_init', function () {
    register_rest_route('wpcompany/v1', '/validate', [
        'methods' => 'POST',
        'callback' => 'wpcompany_validate_request',
        'permission_callback' => '__return_true',
    ]);
});

При вызове без параметра data API вернет HTTP 422 с сообщением об ошибке.

Пример интеграции с плагином Clearfy Pro для улучшения безопасности REST API

Плагин Clearfy Pro позволяет гибко настраивать доступ к REST API, ограничивая его для неавторизованных пользователей или определенных маршрутов.

Если вы хотите дополнительно фильтровать коды ответа или изменять их в зависимости от прав доступа, Clearfy Pro поможет реализовать это без необходимости писать много кода. Подробнее о плагине можно узнать на https://wpshop.ru/clearfy-pro/.

Резюме: ключевые моменты изменения кода ответа REST API WordPress

• Всегда возвращайте объект WP_REST_Response для контроля HTTP-статуса.
• Для кастомных эндпоинтов используйте метод set_status() объекта ответа.
• Для изменения кода стандартных маршрутов применяйте фильтр rest_post_dispatch.
• Для ошибок используйте WP_Error с указанием параметра status.
• Рассмотрите использование плагинов, таких как Clearfy Pro, для дополнительной настройки безопасности и управления REST API.

Таким образом, вы сможете гибко управлять кодами ответов REST API WordPress, повышая информативность и контролируемость взаимодействия вашего сайта с внешними сервисами и приложениями.