Как добавить своё пользовательское поле в REST API WordPress

В процессе разработки сайтов на WordPress часто возникает необходимость добавить собственные пользовательские поля (custom fields) в ответ REST API. Это позволяет использовать API для получения и обновления дополнительной информации, которая не входит в стандартный набор данных записей, страниц или других типов контента.

Что такое REST API в WordPress и почему стоит расширять его

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

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

Как правильно зарегистрировать пользовательское поле в REST API WordPress

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

Рассмотрим пример: допустим, у записей есть пользовательское поле с ключом _wpexpert_custom_note, которое мы хотим включить в API под именем custom_note.

function wpexpert_register_custom_field() {
    register_rest_field('post', // тип записи
        'custom_note', // имя нового поля в API
        array(
            'get_callback' => 'wpexpert_get_custom_note',
            'update_callback' => 'wpexpert_update_custom_note',
            'schema' => array(
                'description' => 'Пользовательская заметка для записи',
                'type' => 'string',
                'context' => array('view', 'edit'),
            ),
        )
    );
}
add_action('rest_api_init', 'wpexpert_register_custom_field');

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

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

В этом коде мы регистрируем новое поле custom_note для типа записи post. Функции получения и обновления данных работают с метаданными записи.

Тестирование и использование добавленного поля в API

После добавления кода можно проверить работу поля через REST API, например, запросом GET:

GET https://ваш-сайт.ru/wp-json/wp/v2/posts/123

В ответе в JSON появится поле custom_note с вашим значением.

Для обновления можно отправить PATCH-запрос с телом:

{
  "custom_note": "Новое значение заметки"
}

Важно, чтобы у пользователя, делающего запросы, были права на редактирование записи.

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

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

register_rest_field('product', 'custom_note', array(...));

Для таксономий используется функция register_rest_field() с типом таксономии, например category или product_cat.

Пример для таксономии категорий:

register_rest_field('category', 'custom_info', array(
    'get_callback' => 'wpexpert_get_category_custom_info',
    'update_callback' => 'wpexpert_update_category_custom_info',
    'schema' => array(
        'description' => 'Дополнительная информация категории',
        'type' => 'string',
        'context' => array('view', 'edit'),
    ),
));

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

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

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

Для интеграции с плагинами WPShop рекомендуем обратить внимание на Clearfy Pro, который упрощает работу с API и метаданными.

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

Добавляя пользовательские поля в API, важно помнить:

• Проверяйте права пользователя в колбэках, чтобы не раскрывать конфиденциальные данные.
• Старайтесь кешировать результаты или минимизировать тяжелые запросы, чтобы не нагружать сервер.
• Используйте схемы данных, чтобы клиент понимал формат возвращаемых данных.
• Обрабатывайте ошибки и валидируйте входящие данные в update_callback.

Например, можно добавить проверку прав в get_callback:

function wpexpert_get_custom_note($object, $field_name, $request) {
    if (!current_user_can('edit_post', $object['id'])) {
        return null;
    }
    return get_post_meta($object['id'], '_wpexpert_custom_note', true);
}

Итог

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

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