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

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

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

Стандартный REST API WordPress позволяет работать с основными данными записей, пользователей и таксономий. Но когда требуется передавать данные из произвольных полей (custom fields) или метаданных, нужно их явно регистрировать для REST API. При этом, если поле должно быть уникальным, необходимо реализовать дополнительную логику проверки.

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

Регистрируем уникальное метаполе для REST API

Для начала создадим метаполе, которое будет использоваться для хранения уникального значения. Допустим, это будет поле unique_code. Чтобы сделать его доступным в REST API, используем функцию register_post_meta с параметром show_in_rest.

add_action('init', 'wpsnippets_register_unique_code_meta');
function wpsnippets_register_unique_code_meta() {
    register_post_meta('post', 'unique_code', [
        'show_in_rest' => true,
        'single' => true,
        'type' => 'string',
        'sanitize_callback' => 'sanitize_text_field',
        'auth_callback' => function() {
            return current_user_can('edit_posts');
        },
    ]);
}

Так мы разрешаем использовать поле unique_code в REST API для записей (post). Параметр auth_callback ограничивает доступ только пользователям с правом редактирования.

Реализуем проверку уникальности при сохранении

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

add_filter('rest_pre_insert_post', 'wpsnippets_validate_unique_code', 10, 2);
function wpsnippets_validate_unique_code($prepared_post, $request) {
    $params = $request->get_params();
    if (isset($params['meta']['unique_code'])) {
        $unique_code = sanitize_text_field($params['meta']['unique_code']);
        $post_id = isset($prepared_post->ID) ? $prepared_post->ID : 0;
        
        // Проверяем, есть ли такая мета у других записей
        $args = [
            'post_type' => 'post',
            'post_status' => 'any',
            'meta_query' => [
                [
                    'key' => 'unique_code',
                    'value' => $unique_code,
                    'compare' => '=',
                ],
            ],
            'fields' => 'ids',
            'posts_per_page' => 1,
        ];
        $query = new WP_Query($args);
        $found_posts = $query->posts;
        
        if (!empty($found_posts)) {
            if ($found_posts[0] != $post_id) {
                return new WP_Error(
                    'rest_unique_code_exists',
                    'Это значение уникального кода уже используется в другой записи.',
                    ['status' => 400]
                );
            }
        }
    }
    return $prepared_post;
}

В коде мы ищем записи с таким же значением unique_code. Если находим и это не текущая редактируемая запись — возвращаем ошибку с кодом 400 и сообщением.

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

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

curl -X POST https://example.com/wp-json/wp/v2/posts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
    "title": "Новая запись",
    "status": "publish",
    "meta": {
        "unique_code": "code123"
    }
}'

Если значение unique_code уже существует, получите ответ с ошибкой и сообщением, что поле должно быть уникальным.

Советы по улучшению и расширению

Кэширование результатов проверки

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

Использование в пользовательских типах записей

Вы можете адаптировать код для любых типов записей, меняя параметр post_type в register_post_meta и WP_Query.

Валидация на стороне клиента

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

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

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

• Clearfy Pro — оптимизация и расширение API, включая кастомные поля.
• WPRemark — комментарии и метаданные с поддержкой REST API.

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