Что такое кастомные эндпоинты REST API в WordPress
REST API — мощный инструмент для взаимодействия с сайтом WordPress, позволяющий получать, создавать, обновлять и удалять данные с помощью HTTP-запросов. Однако стандартный набор эндпоинтов не всегда покрывает специфические задачи, которые могут потребоваться для вашего проекта. В таких случаях создаются кастомные эндпоинты — собственные маршруты API, которые выполняют уникальные функции.
Создание кастомных эндпоинтов позволяет расширить функциональность сайта, интегрироваться с внешними системами или реализовать нестандартные бизнес-логики. В этой статье подробно разберём, как создать такие эндпоинты с примерами и пояснениями.
Регистрация кастомного REST API эндпоинта в WordPress
Для создания собственного эндпоинта используется хук rest_api_init и функция register_rest_route(). Рассмотрим базовый пример регистрации эндпоинта, который возвращает простое сообщение.
add_action('rest_api_init', 'wptavern_register_custom_endpoint');
function wptavern_register_custom_endpoint() {
register_rest_route('wptavern/v1', '/hello', array(
'methods' => 'GET',
'callback' => 'wptavern_custom_hello_callback',
));
}
function wptavern_custom_hello_callback() {
return array('message' => 'Привет из кастомного эндпоинта WP Tavern!');
}
Этот код создаёт маршрут /wp-json/wptavern/v1/hello, который при GET-запросе вернёт JSON с сообщением. Обратите внимание, что префикс wptavern в названиях функций и namespace помогает избежать конфликтов с другими плагинами.
Пояснение параметров
'wptavern/v1'— namespace и версия API;'hello'— путь эндпоинта;'methods' => 'GET'— HTTP метод;'callback'— функция-обработчик запроса.
Обработка параметров в запросе и валидация
Часто нужно принимать параметры от клиента, например, ID пользователя или дату. В WordPress API это реализуется через аргумент args в register_rest_route. Рассмотрим пример эндпоинта, который принимает параметр name и возвращает персональное приветствие.
add_action('rest_api_init', 'wptavern_register_greet_endpoint');
function wptavern_register_greet_endpoint() {
register_rest_route('wptavern/v1', '/greet', array(
'methods' => 'GET',
'callback' => 'wptavern_greet_callback',
'args' => array(
'name' => array(
'required' => true,
'validate_callback' => function($param, $request, $key) {
return is_string($param) && !empty($param);
},
'sanitize_callback' => 'sanitize_text_field',
),
),
));
}
function wptavern_greet_callback($request) {
$name = $request->get_param('name');
return array('message' => "Привет, {$name}!");
}
Тут мы задали обязательный параметр name, указали, как его валидировать и очистить перед использованием. Если параметр не передан или не пройдет проверку, WordPress автоматически вернёт ошибку.
Использование методов POST и обработка данных
Для записи данных или выполнения действий на сервере часто применяют методы POST, PUT или DELETE. Рассмотрим пример эндпоинта, который принимает POST-запрос с JSON-данными и сохраняет их как запись custom post type.
add_action('rest_api_init', 'wptavern_register_post_create_endpoint');
function wptavern_register_post_create_endpoint() {
register_rest_route('wptavern/v1', '/create-post', array(
'methods' => 'POST',
'callback' => 'wptavern_create_post_callback',
'permission_callback' => function() {
return current_user_can('edit_posts');
},
'args' => array(
'title' => array('required' => true),
'content' => array('required' => true),
),
));
}
function wptavern_create_post_callback($request) {
$title = sanitize_text_field($request->get_param('title'));
$content = sanitize_textarea_field($request->get_param('content'));
$new_post = array(
'post_title' => $title,
'post_content' => $content,
'post_status' => 'publish',
'post_type' => 'post',
);
$post_id = wp_insert_post($new_post);
if (is_wp_error($post_id)) {
return new WP_Error('post_creation_failed', 'Не удалось создать запись', array('status' => 500));
}
return array('post_id' => $post_id, 'message' => 'Запись успешно создана');
}
Здесь мы также используем permission_callback, чтобы ограничить доступ только авторизованным пользователям с правами на создание записей. Это важный момент безопасности при создании кастомных API.
Обработка ошибок и правильные HTTP-статусы
При создании API важно корректно обрабатывать ошибки и отдавать правильные HTTP-статусы. WordPress предоставляет класс WP_Error, который удобно использовать для возврата ошибок.
Например, если передан некорректный параметр, возвращаем ошибку с кодом 400:
return new WP_Error('invalid_param', 'Параметр name обязателен и должен быть строкой', array('status' => 400));
Это позволит клиентам API понимать, что пошло не так, и обрабатывать ошибки на своей стороне.
Использование плагинов для упрощения работы с REST API
Хотя WordPress из коробки поддерживает REST API, существуют плагины, которые упрощают создание и управление кастомными эндпоинтами. Например:
- WP REST API Controller — удобный интерфейс для управления доступом и настройкой эндпоинтов без кода;
- Advanced Custom Fields to REST API — добавляет поля ACF в ответы API;
- REST API Helper — набор функций и хуков для расширения стандартного функционала.
Использование таких плагинов ускоряет разработку и помогает избежать ошибок.
Безопасность кастомных эндпоинтов REST API
Создавая собственные маршруты, обязательно учитывайте безопасность. Вот основные рекомендации:
- Используйте
permission_callbackдля проверки прав пользователя; - Валидация и санитизация всех входящих данных;
- Ограничение доступа к чувствительным данным;
- Использование nonce и аутентификации, если API вызывается из фронтенда.
Игнорирование этих правил может привести к уязвимостям и компрометации сайта.
Пример расширенного кастомного эндпоинта с пагинацией и фильтрами
Рассмотрим пример эндпоинта, который возвращает список кастомных записей с возможностью фильтрации по категории и пагинацией.
add_action('rest_api_init', 'wptavern_register_custom_posts_endpoint');
function wptavern_register_custom_posts_endpoint() {
register_rest_route('wptavern/v1', '/custom-posts', array(
'methods' => 'GET',
'callback' => 'wptavern_get_custom_posts_callback',
'args' => array(
'category' => array(
'required' => false,
'sanitize_callback' => 'sanitize_text_field',
),
'page' => array(
'required' => false,
'default' => 1,
'validate_callback' => 'is_numeric',
'sanitize_callback' => 'absint',
),
'per_page' => array(
'required' => false,
'default' => 10,
'validate_callback' => 'is_numeric',
'sanitize_callback' => 'absint',
),
),
));
}
function wptavern_get_custom_posts_callback($request) {
$category = $request->get_param('category');
$page = $request->get_param('page');
$per_page = $request->get_param('per_page');
$args = array(
'post_type' => 'custom_post',
'posts_per_page' => $per_page,
'paged' => $page,
);
if ($category) {
$args['tax_query'] = array(
array(
'taxonomy' => 'custom_category',
'field' => 'slug',
'terms' => $category,
),
);
}
$query = new WP_Query($args);
$posts = array();
foreach ($query->posts as $post) {
$posts[] = array(
'id' => $post->ID,
'title' => get_the_title($post),
'excerpt' => get_the_excerpt($post),
'link' => get_permalink($post),
);
}
return array(
'posts' => $posts,
'total' => $query->found_posts,
'pages' => $query->max_num_pages,
'current_page' => $page,
);
}
Такой эндпоинт позволит гибко получать списки записей с фильтрами и пагинацией, что удобно для фронтенд-приложений и мобильных клиентов.