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

Автор: Татьяна Данилова | Опубликовано: 29.08.2026

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

Зачем добавлять уникальные поля в REST API WordPress

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

Пользовательские метаполя (post meta) с дополнительной информацией о записи.
Произвольные вычисляемые значения, основанные на данных записи.
Внешние данные, связанные с записью, которые не хранятся в базе WordPress.

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

Регистрация уникального поля через register_rest_field

Для добавления уникального поля в REST API используется функция register_rest_field. Она позволяет добавить новое поле к нужному типу записи, указав callback-функции для получения и установки значения.

Сигнатура функции:

register_rest_field( string $object_type, string $attribute, array $args = array() )

Где:

$object_type — тип объекта (например, 'post', 'user', 'page', или ваш кастомный тип записи).
$attribute — название нового поля, которое появится в JSON.
$args — массив с параметрами, включая 'get_callback', 'update_callback' и 'schema'.

Пример добавления метаполя _wpin_custom_field для постов

Допустим, у нас есть метаполе '_wpin_custom_field', которое мы хотим вывести в REST API под ключом 'wpin_custom_field'. Добавим следующий код в functions.php или в свой плагин:

function wpin_register_custom_rest_field() {
  register_rest_field('post', 'wpin_custom_field', [
    'get_callback' => 'wpin_get_custom_field',
    'update_callback' => 'wpin_update_custom_field',
    'schema' => [
      'description' => 'Уникальное пользовательское поле WPin',
      'type' => 'string',
      'context' => ['view', 'edit']
    ]
  ]);
}
add_action('rest_api_init', 'wpin_register_custom_rest_field');

function wpin_get_custom_field($object, $field_name, $request) {
  return get_post_meta($object['id'], '_wpin_custom_field', true);
}

function wpin_update_custom_field($value, $object, $field_name) {
  if (!is_string($value)) {
    return new WP_Error('rest_invalid_param', 'Значение должно быть строкой', ['status' => 400]);
  }
  return update_post_meta($object->ID, '_wpin_custom_field', sanitize_text_field($value));
}

Объяснение:

При инициализации REST API регистрируем новое поле 'wpin_custom_field' для типа 'post'.
get_callback читает метаполе с помощью get_post_meta и возвращает его значение.
update_callback позволяет обновить метаполе через REST API, с валидацией и очисткой данных.
schema описывает тип и контекст поля, что важно для документации и валидаторов.

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

Если вы хотите расширить REST API без ручного кода, можно воспользоваться готовыми плагинами. Вот несколько полезных:

ACF to REST API — добавляет все поля ACF в REST API автоматически.
WP REST API Controller — удобный интерфейс для настройки отображения полей и прав доступа.
Custom Fields to REST API — простой плагин, позволяющий выбрать метаполя для вывода.

Но если вам нужны гибкие решения и контроль, лучше писать свои callback-функции, как показано выше.

Работа с кастомными типами записей и таксономиями

Добавление уникальных полей в REST API для кастомных типов записей и таксономий происходит по тому же принципу. Например, для типа 'product' из WooCommerce или собственного типа 'portfolio' можно сделать так:

function wpin_register_portfolio_custom_field() {
  register_rest_field('portfolio', 'wpin_portfolio_extra', [
    'get_callback' => function($object) {
      return get_post_meta($object['id'], '_wpin_portfolio_extra', true);
    },
    'schema' => [
      'description' => 'Дополнительное поле портфолио',
      'type' => 'string',
      'context' => ['view', 'edit']
    ]
  ]);
}
add_action('rest_api_init', 'wpin_register_portfolio_custom_field');

Такой подход легко адаптируется под любые типы данных.

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

Для таксономий также можно регистрировать поля, используя register_rest_field для типа таксономии, например 'category' или 'product_cat'. В callback-функции можно получать метаданные через функции вроде get_term_meta.

Безопасность и производительность при расширении REST API

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

Права доступа: В callback-функциях проверяйте, имеет ли пользователь право видеть или менять поле. Это можно сделать через current_user_can() или проверку контекста запроса.
Валидация данных: Обязательно валидируйте и фильтруйте входящие данные в update_callback, чтобы не получить уязвимости.
Кэширование: Если вычисляемое поле требует сложных запросов, стоит кешировать результат для ускорения работы API.

Пример использования нового поля в запросе REST API

После регистрации поля вы можете получить его в ответе REST API, например:

GET https://site.ru/wp-json/wp/v2/posts/123

В ответе появится ключ wpin_custom_field с нужным значением. Чтобы обновить поле, отправьте PATCH-запрос с JSON:

PATCH https://site.ru/wp-json/wp/v2/posts/123
{
  "wpin_custom_field": "Новое значение"
}

Обратите внимание, что для обновления нужно иметь соответствующие права.

Использование с плагином Clearfy Pro для оптимизации

Если вы используете Clearfy Pro, он поможет отключить ненужные REST API маршруты и защитить сайт от лишних запросов. В сочетании с добавлением своих полей это позволяет тонко настроить API под ваши задачи и повысить безопасность.

Выводы и рекомендации

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

⭐⭐⭐⭐⭐