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

Почему важно расширять WP REST API дополнительными полями

WordPress REST API предоставляет мощные возможности для взаимодействия с сайтом через HTTP-запросы. Однако по умолчанию в ответах API возвращаются только стандартные поля записи, что часто недостаточно для сложных проектов. Особенно это актуально, если вы используете кастомные типы записей (Custom Post Types) и кастомные поля (Custom Fields), которые содержат важную для фронтенда или внешних систем информацию.

Добавление дополнительных полей в ответ REST API позволяет:

Передавать всю необходимую информацию в одном запросе без дополнительных обходных путей;
Оптимизировать работу фронтенда, уменьшая количество запросов;
Расширять стандартный функционал WordPress под нужды конкретного проекта.

В этой статье мы подробно разберём, как добавить кастомные поля в WP REST API для кастомных типов записей, рассмотрим практические примеры и уделим внимание безопасности.

Регистрация дополнительных полей в WP REST API

Для добавления новых полей в ответ API необходимо использовать функцию register_rest_field. Она позволяет связать дополнительное поле с типом записи и задать callback-функции для получения и обновления данных.

Рассмотрим пример, когда у нас есть кастомный тип записи book, и мы хотим добавить в ответ API поле author_name, которое хранится в метаполе _author_name.

function 2wp_register_book_author_name_field() {
    register_rest_field('book', 'author_name', [
        'get_callback'    => '2wp_get_book_author_name',
        'update_callback' => '2wp_update_book_author_name',
        'schema'          => [
            'description' => 'Имя автора книги',
            'type'        => 'string',
            'context'     => ['view', 'edit'],
        ],
    ]);
}
add_action('rest_api_init', '2wp_register_book_author_name_field');

function 2wp_get_book_author_name($object, $field_name, $request) {
    return get_post_meta($object['id'], '_author_name', true);
}

function 2wp_update_book_author_name($value, $object, $field_name) {
    if (!is_string($value)) {
        return new WP_Error('rest_invalid_param', 'Неверный формат имени автора', ['status' => 400]);
    }
    return update_post_meta($object->ID, '_author_name', sanitize_text_field($value));
}

В этом коде мы регистрируем поле author_name для типа записи book. При получении записи через REST API поле будет возвращено, а при обновлении через метод POST или PUT — сохранено.

Контекст и безопасность

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

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

Добавление сложных полей и форматов данных

Если вы используете в метаполях сложные структуры — например, массивы, JSON или объекты — можно возвращать их в нужном формате, но убедитесь, что они корректно сериализуются и десериализуются.

Пример добавления поля с массивом тегов, сохранённых в метаполе _book_tags:

function 2wp_register_book_tags_field() {
    register_rest_field('book', 'book_tags', [
        'get_callback'    => '2wp_get_book_tags',
        'update_callback' => '2wp_update_book_tags',
        'schema'          => [
            'description' => 'Теги книги',
            'type'        => 'array',
            'items'       => [
                'type' => 'string'
            ],
            'context'     => ['view', 'edit'],
        ],
    ]);
}
add_action('rest_api_init', '2wp_register_book_tags_field');

function 2wp_get_book_tags($object) {
    $tags = get_post_meta($object['id'], '_book_tags', true);
    return is_array($tags) ? $tags : [];
}

function 2wp_update_book_tags($value, $object) {
    if (!is_array($value)) {
        return new WP_Error('rest_invalid_param', 'Теги должны быть массивом строк', ['status' => 400]);
    }
    $sanitized = array_map('sanitize_text_field', $value);
    return update_post_meta($object->ID, '_book_tags', $sanitized);
}

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

Использование плагинов для расширения REST API

Если вы не хотите писать код самостоятельно, можно использовать плагины, облегчающие добавление полей в REST API:

ACF to REST API — расширяет стандартный REST API, добавляя все поля Advanced Custom Fields (ACF). Очень полезно, если вы работаете с ACF.
WP REST API Controller — позволяет управлять полями и настройками REST API через админку, без кода.
Clearfy Pro — известен своими инструментами для оптимизации и управления WordPress, в том числе расширяет возможности REST API.

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

Практические рекомендации и отладка

При разработке расширений REST API учитывайте следующие моменты:

Проверяйте права доступа — используйте permission_callback в register_rest_route или проверяйте в callback-функциях, чтобы обезопасить данные.
Тестируйте изменения через инструменты, например Postman или встроенный REST API тестер в браузере.
Используйте префиксы в названиях функций (например, 2wp_) для избежания конфликтов с другими плагинами и темами.
Следите за производительностью — не добавляйте в API тяжёлые запросы без необходимости, кешируйте результаты, если нужно.

В случае возникновения ошибок смотрите логи сервера и включайте WP_DEBUG для получения подробной информации.