Что такое REST API в WordPress и зачем создавать кастомные эндпоинты
WordPress с версии 4.7 имеет встроенный REST API — мощный инструмент для работы с данными сайта через HTTP-запросы. Он позволяет взаимодействовать с контентом, пользователями, комментариями и другими сущностями через стандартные методы GET, POST, PUT, DELETE.
Однако стандартные эндпоинты не всегда покрывают все задачи. Часто требуется создать свои кастомные маршруты (эндпоинты), чтобы реализовать уникальную бизнес-логику, интеграцию с внешними сервисами или предоставить API для мобильных приложений и SPA (Single Page Application).
В этой статье рассмотрим, как создавать кастомные REST API эндпоинты в WordPress с примерами и уделим внимание важным аспектам безопасности.
Регистрация кастомного эндпоинта: базовый пример
Для регистрации собственного маршрута в REST API WordPress используется функция register_rest_route(). Она вызывается обычно на хуке rest_api_init.
Пример регистрации простого GET эндпоинта, который возвращает приветственное сообщение:
add_action('rest_api_init', 'wpedu_register_custom_endpoint');
function wpedu_register_custom_endpoint() {
register_rest_route('wpedu/v1', '/hello/', [
'methods' => 'GET',
'callback' => 'wpedu_hello_endpoint_handler',
'permission_callback' => '__return_true',
]);
}
function wpedu_hello_endpoint_handler() {
return ['message' => 'Привет от WPedu!'];
}Объяснения:
'wpedu/v1'— пространство имён и версия API. Рекомендуется использовать уникальный префикс.'/hello/'— маршрут эндпоинта.'methods' => 'GET'— HTTP-метод, с которым работает эндпоинт.'callback'— функция-обработчик запроса.'permission_callback'— функция проверки прав доступа. Здесь__return_true, значит доступ открыт всем.
Передача параметров и валидация данных в кастомных эндпоинтах
Часто нужно принимать параметры от клиента. В REST API параметры передаются через URL, тело запроса или заголовки.
Добавим эндпоинт, который принимает параметр name и возвращает кастомное приветствие:
add_action('rest_api_init', 'wpedu_register_greet_endpoint');
function wpedu_register_greet_endpoint() {
register_rest_route('wpedu/v1', '/greet/', [
'methods' => 'GET',
'callback' => 'wpedu_greet_handler',
'permission_callback' => '__return_true',
'args' => [
'name' => [
'required' => true,
'validate_callback' => function($param, $request, $key) {
return is_string($param) && !empty($param);
},
'sanitize_callback' => 'sanitize_text_field',
],
],
]);
}
function wpedu_greet_handler($request) {
$name = $request->get_param('name');
return ['message' => 'Привет, ' . $name . '! Добро пожаловать на wpedu.ru'];
}Здесь мы определили параметр name как обязательный, с валидацией и очисткой данных. Это уменьшает риск ошибок и атак.
Обработка POST-запросов и создание ресурса
REST API часто используют для создания и обновления данных. Рассмотрим пример, как создать простую заметку (post type 'note') через POST-запрос.
Сначала зарегистрируем новый тип записи с поддержкой REST API:
add_action('init', 'wpedu_register_note_post_type');
function wpedu_register_note_post_type() {
register_post_type('note', [
'label' => 'Заметки',
'public' => false,
'show_in_rest' => true,
'supports' => ['title', 'editor'],
]);
}Далее создадим эндпоинт для создания заметки:
add_action('rest_api_init', 'wpedu_register_create_note_endpoint');
function wpedu_register_create_note_endpoint() {
register_rest_route('wpedu/v1', '/note/create', [
'methods' => 'POST',
'callback' => 'wpedu_create_note_handler',
'permission_callback' => 'wpedu_check_create_note_permissions',
'args' => [
'title' => [
'required' => true,
'sanitize_callback' => 'sanitize_text_field',
],
'content' => [
'required' => false,
'sanitize_callback' => 'sanitize_textarea_field',
],
],
]);
}
function wpedu_create_note_handler($request) {
$title = $request->get_param('title');
$content = $request->get_param('content');
$post_id = wp_insert_post([
'post_type' => 'note',
'post_title' => $title,
'post_content' => $content,
'post_status' => 'publish',
]);
if (is_wp_error($post_id)) {
return new WP_Error('cannot_create', 'Не удалось создать заметку', ['status' => 500]);
}
return ['success' => true, 'note_id' => $post_id];
}
function wpedu_check_create_note_permissions() {
return current_user_can('edit_posts');
}Здесь мы проверяем права пользователя (только авторизованные с возможностью редактирования постов могут создавать заметки), принимаем данные, создаём новую запись и возвращаем результат.
Безопасность кастомных REST API эндпоинтов
Безопасность — ключевой аспект при работе с REST API. Вот основные рекомендации:
- Всегда используйте
permission_callbackдля проверки прав доступа и аутентификации. - Валидация и санитизация входящих данных — обязательны, чтобы предотвратить инъекции и ошибки.
- При необходимости используйте nonce или OAuth для дополнительной защиты.
- Логируйте ошибки и подозрительные запросы для анализа.
Если эндпоинт доступен публично, ограничьте набор данных, которые он возвращает, чтобы не раскрывать чувствительную информацию.
Полезные плагины для расширения и отладки REST API
Для работы и тестирования REST API в WordPress можно использовать несколько полезных плагинов:
- WP REST API Controller — позволяет управлять доступом к REST API, включая включение/отключение эндпоинтов.
- REST API Toolbox — настройка авторизации, логирование запросов.
- Postman (не плагин, а инструмент) — удобный клиент для тестирования REST API запросов.
Эти инструменты помогут ускорить разработку и повысить качество вашего API.
Заключение: когда и почему стоит создавать кастомные эндпоинты в WordPress
Кастомные REST API эндпоинты в WordPress позволяют создавать гибкие и масштабируемые решения, интегрировать сайт с внешними сервисами, строить современные интерфейсы и мобильные приложения.
Используйте приведённые примеры и рекомендации, чтобы создавать надёжные и безопасные API, которые помогут вашему проекту развиваться и удовлетворять запросы пользователей.