WP REST API v2: создание кастомных эндпоинтов с метаполями и фильтрацией

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

Что такое метаполя в WordPress и зачем их использовать в REST API

Метаполя (post meta) — это дополнительные данные, которые можно добавить к любому посту, странице или кастомному типу записи. Например, для интернет-магазина это может быть цена товара, для событий — дата проведения, для блога — рейтинг статьи. Метаполя позволяют расширять стандартную структуру данных WordPress без изменения базы данных.

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

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

Для начала зарегистрируем новый эндпоинт, который будет возвращать посты с указанными метаполями. Используем хук rest_api_init и функцию register_rest_route. Ниже пример функции wpapi_register_custom_endpoint, которую нужно добавить в файл functions.php вашей темы или в плагин.

function wpapi_register_custom_endpoint() {
    register_rest_route( 'wpapi/v1', '/products/', array(
        'methods'  => 'GET',
        'callback' => 'wpapi_get_products_with_meta',
        'args'     => array(
            'price_min' => array(
                'validate_callback' => 'is_numeric',
            ),
            'price_max' => array(
                'validate_callback' => 'is_numeric',
            ),
        ),
        'permission_callback' => '__return_true',
    ));
}
add_action( 'rest_api_init', 'wpapi_register_custom_endpoint' );

Этот эндпоинт будет доступен по адресу /wp-json/wpapi/v1/products/ и поддерживать фильтрацию по минимальной и максимальной цене.

Обработка запроса и получение постов с метаполями и фильтрацией

Теперь реализуем функцию wpapi_get_products_with_meta, которая получит параметры запроса, сформирует WP_Query с мета-запросом и вернёт отфильтрованные данные.

function wpapi_get_products_with_meta( WP_REST_Request $request ) {
    $price_min = $request->get_param('price_min');
    $price_max = $request->get_param('price_max');

    $meta_query = array('relation' => 'AND');

    if ( $price_min !== null ) {
        $meta_query[] = array(
            'key'     => 'price',
            'value'   => $price_min,
            'type'    => 'NUMERIC',
            'compare' => '>='
        );
    }
    if ( $price_max !== null ) {
        $meta_query[] = array(
            'key'     => 'price',
            'value'   => $price_max,
            'type'    => 'NUMERIC',
            'compare' => '<='
        );
    }

    $args = array(
        'post_type'      => 'product',
        'posts_per_page' => 10,
        'meta_query'     => $meta_query,
        'orderby'        => 'meta_value_num',
        'meta_key'       => 'price',
        'order'          => 'ASC',
    );

    $query = new WP_Query( $args );
    $posts = array();

    foreach ( $query->posts as $post ) {
        $posts[] = array(
            'id'    => $post->ID,
            'title' => get_the_title( $post ),
            'price' => get_post_meta( $post->ID, 'price', true ),
            'link'  => get_permalink( $post ),
        );
    }

    return rest_ensure_response( $posts );
}

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

Добавление метаполей в стандартные REST API ответы

Если вы хотите, чтобы метаполя автоматически возвращались в стандартных эндпоинтах WP REST API, можно зарегистрировать метаполя через функцию register_meta с параметром show_in_rest.

function wpapi_register_price_meta() {
    register_post_meta( 'product', 'price', array(
        'type'         => 'number',
        'single'       => true,
        'show_in_rest' => true,
        'sanitize_callback' => 'wpapi_sanitize_price',
    ));
}
add_action( 'init', 'wpapi_register_price_meta' );

function wpapi_sanitize_price( $value ) {
    return floatval( $value );
}

После этого при запросе стандартного эндпоинта /wp-json/wp/v2/product в ответе будет поле price.

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

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

Итоги и рекомендации

Создание кастомных REST API эндпоинтов с поддержкой метаполей и фильтрации — важная задача для расширенных проектов на WordPress. Такой подход позволяет интегрировать WordPress с внешними приложениями, мобильными клиентами и SPA с точным контролем данных.

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