WordPress с версии 4.7 имеет встроенный REST API, который позволяет взаимодействовать с сайтом через HTTP-запросы. Это мощный инструмент для разработчиков, который расширяет возможности интеграции, мобильных приложений и SPA (Single Page Application). В этой статье мы подробно рассмотрим, как создать собственный REST API endpoint в WordPress на примере реального кода и разберём, как это использовать для решения конкретных задач.
Что такое REST API в WordPress и зачем создавать собственные endpoints
REST API — это набор URL, которые предоставляют доступ к данным сайта и позволяют выполнять операции чтения, создания, обновления и удаления (CRUD) через HTTP-запросы. WordPress из коробки содержит множество стандартных endpoints для работы с постами, страницами, пользователями и так далее.
Однако часто возникает необходимость расширить этот функционал и добавить свои собственные endpoints. Например, можно создать API для получения пользовательских данных, кастомных записей, или для реализации специфичной логики, которой нет в стандартном API.
Создавая собственный endpoint, вы управляете структурой и содержимым ответа, а также логикой обработки запросов. Это открывает новые возможности для интеграции и кастомизации.
Как зарегистрировать собственный REST API endpoint в WordPress
Для регистрации собственного endpoint используется функция register_rest_route(), которую нужно вызывать в хук rest_api_init. Рассмотрим базовый пример регистрации маршрута.
add_action('rest_api_init', 'wpabout_register_custom_endpoint');
function wpabout_register_custom_endpoint() {
register_rest_route('wpabout/v1', '/hello/', array(
'methods' => 'GET',
'callback' => 'wpabout_hello_endpoint_handler',
));
}
function wpabout_hello_endpoint_handler(WP_REST_Request $request) {
return array('message' => 'Привет от WPAbout REST API!');
}В этом примере мы создаём endpoint по адресу /wp-json/wpabout/v1/hello/, который при GET-запросе возвращает простой JSON с приветствием.
Обратите внимание на структуру регистрации: первый параметр — пространство имён и версия API (wpabout/v1), второй — маршрут (/hello/), третий — массив с настройками, где указывается метод запроса и функция-обработчик.
Разбор параметров и возможностей
Функция register_rest_route() позволяет задавать много дополнительных параметров, таких как:
- args — описание и валидация принимаемых параметров;
- permission_callback — функция проверки прав доступа;
- methods — поддерживаемые HTTP-методы (GET, POST, PUT, DELETE и др.).
Например, если вы хотите, чтобы endpoint принимал параметр name и возвращал персонализированное сообщение, можно добавить валидацию параметров:
add_action('rest_api_init', 'wpabout_register_personalized_endpoint');
function wpabout_register_personalized_endpoint() {
register_rest_route('wpabout/v1', '/hello/', array(
'methods' => 'GET',
'callback' => 'wpabout_personalized_hello_handler',
'args' => array(
'name' => array(
'required' => false,
'validate_callback' => function($param, $request, $key) {
return is_string($param);
}
),
),
));
}
function wpabout_personalized_hello_handler(WP_REST_Request $request) {
$name = $request->get_param('name');
if ($name) {
$message = 'Привет, ' . sanitize_text_field($name) . '! Добро пожаловать в WPAbout REST API.';
} else {
$message = 'Привет от WPAbout REST API!';
}
return array('message' => $message);
}Теперь, сделав запрос /wp-json/wpabout/v1/hello/?name=Иван, вы получите персонализированное приветствие.
Добавление проверки прав доступа к REST API endpoint
Очень важно контролировать, кто может использовать ваш API, особенно если данные чувствительные или операции изменяют состояние сайта. Для этого служит параметр permission_callback, который должен возвращать true, если доступ разрешён, и false или WP_Error — если нет.
Пример ограничения доступа только для авторизованных пользователей:
add_action('rest_api_init', 'wpabout_register_secure_endpoint');
function wpabout_register_secure_endpoint() {
register_rest_route('wpabout/v1', '/private-data/', array(
'methods' => 'GET',
'callback' => 'wpabout_private_data_handler',
'permission_callback' => function() {
return is_user_logged_in();
}
));
}
function wpabout_private_data_handler(WP_REST_Request $request) {
$current_user = wp_get_current_user();
return array(
'user_id' => $current_user->ID,
'user_login' => $current_user->user_login,
'message' => 'Это приватные данные, доступные только авторизованным.'
);
}Если неавторизованный пользователь попробует обратиться к этому endpoint, REST API вернёт ошибку с кодом 401 Unauthorized.
Работа с кастомными типами записей через собственный REST API endpoint
Часто нужно создавать API для работы с кастомными типами записей (Custom Post Types, CPT). WordPress автоматически добавляет REST API для CPT при правильной регистрации, но иногда требуется создать более специфичный endpoint.
Рассмотрим пример, где у нас есть CPT book, и мы хотим создать endpoint, который возвращает список книг с дополнительными фильтрами.
add_action('rest_api_init', 'wpabout_register_books_endpoint');
function wpabout_register_books_endpoint() {
register_rest_route('wpabout/v1', '/books/', array(
'methods' => 'GET',
'callback' => 'wpabout_get_books_handler',
'args' => array(
'genre' => array(
'required' => false,
'sanitize_callback' => 'sanitize_text_field',
),
'limit' => array(
'required' => false,
'default' => 10,
'validate_callback' => function($param, $request, $key) {
return is_numeric($param) && $param > 0 && $param <= 100;
},
),
),
));
}
function wpabout_get_books_handler(WP_REST_Request $request) {
$genre = $request->get_param('genre');
$limit = $request->get_param('limit');
$args = array(
'post_type' => 'book',
'posts_per_page' => $limit,
'post_status' => 'publish',
);
if ($genre) {
$args['tax_query'] = array(
array(
'taxonomy' => 'genre',
'field' => 'slug',
'terms' => $genre,
),
);
}
$query = new WP_Query($args);
$books = array();
if ($query->have_posts()) {
while ($query->have_posts()) {
$query->the_post();
$books[] = array(
'id' => get_the_ID(),
'title' => get_the_title(),
'link' => get_permalink(),
);
}
wp_reset_postdata();
}
return $books;
}Теперь, сделав запрос /wp-json/wpabout/v1/books/?genre=fantasy&limit=5, вы получите список из 5 книг жанра «фэнтези» с основными данными.
Преимущества собственного endpoint для кастомных данных
Такой подход позволяет:
- Оптимизировать вывод, возвращая только нужные поля;
- Добавлять произвольную бизнес-логику;
- Реализовывать кастомные фильтры и параметры;
- Обеспечивать контроль доступа и безопасность;
- Упрощать интеграцию с внешними сервисами.
Полезные плагины для работы с REST API в WordPress
Для упрощения создания и тестирования REST API endpoints рекомендуем обратить внимание на несколько плагинов:
- WP REST API Controller — позволяет управлять доступом и настройками стандартных REST API маршрутов без кода.
- REST API Console — удобный инструмент для тестирования запросов прямо из админки.
- Advanced Custom Fields (ACF) — расширяет возможности REST API, добавляя поля ACF в ответы API.
Используя эти плагины, можно быстро настроить и отладить собственные endpoints или расширить стандартный функционал.
Отладка и тестирование собственного REST API endpoint
Для отладки собственного API удобно использовать:
- Postman — мощный клиент для HTTP-запросов с возможностью сохранять коллекции и автоматизировать тесты;
- cURL — простой инструмент командной строки для отправки запросов;
- Встроенный браузер — для GET-запросов можно просто открыть URL.
В процессе разработки проверяйте корректность передачи параметров, ответы сервера, а также обрабатывайте ошибки в функциях обработчика.
Для возврата ошибки используйте объект WP_Error с соответствующим HTTP кодом, например:
return new WP_Error('rest_forbidden', 'Доступ запрещён', array('status' => 403));Резюме: как расширять возможности WordPress через собственные REST API endpoints
Создание собственных REST API endpoints — отличный способ добавить уникальную функциональность, интегрировать сайт с внешними сервисами и улучшить пользовательский опыт. Важно грамотно проектировать маршруты, контролировать доступ и обрабатывать ошибки.
WPAbout рекомендует всегда тщательно тестировать API и использовать возможности WordPress для безопасности и производительности. Примеры, приведённые в статье, можно использовать как шаблоны для собственных проектов.