Как создать собственный REST API эндпоинт в WordPress с фильтрами и параметрами

Автор: Ярослав Смирнов | Опубликовано: 24.12.2025

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

Что такое REST API эндпоинт в WordPress

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

Создание собственного эндпоинта позволяет:

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

Как зарегистрировать собственный REST API эндпоинт в WordPress

Для регистрации нового эндпоинта используется функция register_rest_route, которую нужно вызывать в хуке rest_api_init. Рассмотрим пример регистрации эндпоинта /wptavern/v1/custom-posts, который вернёт список записей кастомного типа с фильтрами.

add_action('rest_api_init', 'wptavern_register_custom_endpoint');
function wptavern_register_custom_endpoint() {
    register_rest_route('wptavern/v1', '/custom-posts', array(
        'methods' => 'GET',
        'callback' => 'wptavern_get_custom_posts',
        'args' => array(
            'category' => array(
                'required' => false,
                'validate_callback' => 'is_numeric',
            ),
            'per_page' => array(
                'required' => false,
                'default' => 10,
                'validate_callback' => function($param, $request, $key) {
                    return is_numeric($param) && $param > 0 && $param <= 100;
                },
            ),
        ),
        'permission_callback' => '__return_true',
    ));
}

В данном коде мы создаём маршрут wptavern/v1/custom-posts с методом GET, указываем функцию-обработчик и описываем параметры запроса: category и per_page.

Обработка параметров и фильтрация данных

Теперь напишем функцию-обработчик, которая получит записи кастомного типа product с учетом фильтра по категории и количества записей на страницу.

function wptavern_get_custom_posts(WP_REST_Request $request) {
    $category = $request->get_param('category');
    $per_page = $request->get_param('per_page');

    $args = array(
        'post_type' => 'product',
        'posts_per_page' => $per_page,
    );

    if ($category) {
        $args['tax_query'] = array(
            array(
                'taxonomy' => 'product_cat',
                'field' => 'term_id',
                'terms' => intval($category),
            ),
        );
    }

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

    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $posts[] = array(
                'id' => get_the_ID(),
                'title' => get_the_title(),
                'link' => get_permalink(),
                'excerpt' => get_the_excerpt(),
            );
        }
        wp_reset_postdata();
    }

    return rest_ensure_response($posts);
}

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

Добавление собственной валидации и обработка ошибок

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

Если необходимо, можно возвращать кастомные ошибки с помощью new WP_Error:

function wptavern_get_custom_posts(WP_REST_Request $request) {
    $category = $request->get_param('category');
    $per_page = $request->get_param('per_page');

    if ($category && !term_exists($category, 'product_cat')) {
        return new WP_Error(
            'invalid_category',
            'Категория с таким ID не существует',
            array('status' => 400)
        );
    }

    // Остальной код запроса...
}

Таким образом, если клиент передаст неверный ID категории, он получит понятное сообщение об ошибке и код 400.

Как протестировать и использовать собственный эндпоинт

Для тестирования созданного эндпоинта можно использовать инструменты, например, Postman или curl. Пример запроса с параметрами:

curl 'https://ваш-сайт.ru/wp-json/wptavern/v1/custom-posts?category=5&per_page=3'

Ответ будет в формате JSON с данными по записям, соответствующим фильтрам.

Кроме того, такой эндпоинт легко использовать в JavaScript на фронтенде, например, через fetch:

fetch('https://ваш-сайт.ru/wp-json/wptavern/v1/custom-posts?category=5&per_page=3')
  .then(response => response.json())
  .then(data => {
    console.log(data);
    // Здесь можно отобразить данные на странице
  });

Примеры плагинов для расширения REST API в WordPress

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

WP REST API Controller — позволяет удобно настраивать доступ и отображение полей в API через админку.
Clearfy Pro — имеет опции для оптимизации и управления REST API, включая отключение ненужных эндпоинтов.
WPGPT — помогает интегрировать GPT-модели с WordPress через REST API.

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