WordPress с версии 4.7 имеет мощный встроенный REST API, который позволяет создавать, читать, обновлять и удалять данные сайта через HTTP-запросы. В этой статье мы разберём, как добавить собственный REST API endpoint, чтобы расширить функциональность сайта и интегрировать его с внешними сервисами или мобильными приложениями.
Что такое REST API endpoint в WordPress и зачем он нужен
REST API endpoint — это URL, который обрабатывает HTTP-запросы и возвращает данные в формате JSON. По умолчанию WordPress предоставляет множество готовых endpoint-ов для работы с постами, пользователями и другими сущностями. Но часто возникает необходимость создать свой собственный endpoint для специфичных задач — например, получить данные из кастомных таблиц, обработать форму, или интегрировать сторонний сервис.
Создание собственного endpoint — это расширение возможностей вашего сайта и удобный способ взаимодействия с ним на уровне программирования.
Регистрация собственного REST API endpoint в WordPress
Для регистрации своего endpoint-а используйте хук rest_api_init. Внутри коллбэка вызывается функция register_rest_route(), в которой указываются namespace, путь, методы и обработчик.
Пример регистрации простого endpoint-а:
add_action('rest_api_init', 'wpconfig_register_custom_endpoint');
function wpconfig_register_custom_endpoint() {
register_rest_route('wpconfig/v1', '/hello/', [
'methods' => 'GET',
'callback' => 'wpconfig_handle_hello_endpoint',
'permission_callback' => '__return_true',
]);
}
function wpconfig_handle_hello_endpoint(WP_REST_Request $request) {
return [
'message' => 'Привет от WPConfig!',
'time' => current_time('mysql')
];
}В этом примере создаётся GET запрос по адресу /wp-json/wpconfig/v1/hello/, который возвращает простое приветствие и текущее время.
Пояснение параметров register_rest_route
- namespace — пространство имён, чтобы избежать конфликтов, обычно указывают свой префикс и версию API.
- route — путь endpoint-а относительно namespace.
- methods — HTTP-методы, которые поддерживает endpoint (GET, POST, PUT, DELETE).
- callback — функция-обработчик запроса.
- permission_callback — функция проверки прав доступа. В примере мы разрешаем всем обращаться к endpoint-у.
Обработка входящих параметров и валидация
REST API позволяет принимать параметры запроса как из URL, так и из тела запроса (для POST). Рассмотрим пример, где endpoint принимает параметр name и возвращает персональное приветствие.
add_action('rest_api_init', function() {
register_rest_route('wpconfig/v1', '/greet/', [
'methods' => 'GET',
'callback' => 'wpconfig_handle_greet_endpoint',
'args' => [
'name' => [
'required' => true,
'validate_callback' => function($param, $request, $key) {
return is_string($param) && strlen($param) > 0;
},
'sanitize_callback' => 'sanitize_text_field'
]
],
'permission_callback' => '__return_true'
]);
});
function wpconfig_handle_greet_endpoint(WP_REST_Request $request) {
$name = $request->get_param('name');
return [
'message' => 'Привет, ' . $name . '!',
];
}В этом примере параметр name обязателен, валидируется и очищается. Если параметр не будет передан или не пройдет валидацию, API вернёт ошибку.
Добавление проверки прав доступа на REST API endpoint
Важно контролировать, кто может вызывать ваш endpoint, особенно если он работает с приватными данными или изменяет состояние сайта. Для этого используют параметр permission_callback.
Пример проверки, что пользователь авторизован и имеет право редактировать записи:
add_action('rest_api_init', function() {
register_rest_route('wpconfig/v1', '/private-data/', [
'methods' => 'GET',
'callback' => 'wpconfig_private_data_handler',
'permission_callback' => function() {
return current_user_can('edit_posts');
}
]);
});
function wpconfig_private_data_handler(WP_REST_Request $request) {
// Возвращаем приватные данные
return [
'secret' => 'Это защищённая информация',
'user' => wp_get_current_user()->user_login
];
}Теперь endpoint доступен только авторизованным пользователям с правом редактирования записей.
Практические примеры использования собственного REST API endpoint
1. Получение кастомных данных из таблицы базы данных
Допустим, у вас есть кастомная таблица wp_custom_data, из которой нужно получить записи через API.
add_action('rest_api_init', function() {
register_rest_route('wpconfig/v1', '/custom-data/', [
'methods' => 'GET',
'callback' => 'wpconfig_get_custom_data',
'permission_callback' => '__return_true'
]);
});
function wpconfig_get_custom_data(WP_REST_Request $request) {
global $wpdb;
$table = $wpdb->prefix . 'custom_data';
$results = $wpdb->get_results("SELECT * FROM $table", ARRAY_A);
return $results;
}Такой endpoint позволяет внешним системам получить данные из вашей кастомной таблицы.
2. Создание записи через POST запрос
Можно создать endpoint, который принимает данные и создаёт новую запись типа «post».
add_action('rest_api_init', function() {
register_rest_route('wpconfig/v1', '/create-post/', [
'methods' => 'POST',
'callback' => 'wpconfig_create_post',
'permission_callback' => function() {
return current_user_can('edit_posts');
},
'args' => [
'title' => [
'required' => true,
'sanitize_callback' => 'sanitize_text_field'
],
'content' => [
'required' => true
]
]
]);
});
function wpconfig_create_post(WP_REST_Request $request) {
$title = $request->get_param('title');
$content = $request->get_param('content');
$post_id = wp_insert_post([
'post_title' => $title,
'post_content' => $content,
'post_status' => 'draft',
'post_type' => 'post'
]);
if (is_wp_error($post_id)) {
return new WP_Error('post_creation_failed', 'Не удалось создать запись', ['status' => 500]);
}
return [
'message' => 'Запись создана успешно',
'post_id' => $post_id
];
}Полезные плагины для работы с REST API в WordPress
Хотя WordPress имеет мощный встроенный REST API, для специфичных задач можно использовать плагины:
- WP REST API Controller — позволяет легко настраивать, какие поля и эндпоинты доступны.
- Advanced Custom Fields to REST API — расширяет стандартный API, добавляя данные из ACF.
- JWT Authentication for WP REST API — добавляет поддержку JWT-токенов для авторизации запросов.
Использование этих плагинов снижает необходимость писать много собственного кода и упрощает интеграцию.
Отладка и тестирование REST API endpoint
Для проверки и отладки API удобно использовать инструменты:
- Postman — мощный клиент для отправки HTTP-запросов с возможностью настройки заголовков, тела и параметров.
- cURL — командная утилита для запросов из терминала.
- WP-CLI — можно писать скрипты для работы с API.
Также не забывайте проверять правильность обработки ошибок и возвращать соответствующие HTTP-коды.
Итоговые рекомендации по созданию REST API endpoint в WordPress
При разработке собственных endpoint-ов:
- Обязательно используйте
permission_callbackдля безопасности. - Валидация и санитизация входящих данных снижают риски и ошибки.
- Используйте namespace для удобства и предотвращения конфликтов.
- Пишите понятные сообщения об ошибках и правильные HTTP-статусы.
- Документируйте свои endpoint-ы, чтобы другие разработчики могли ими пользоваться.
Создание собственного REST API endpoint — мощный инструмент для расширения и интеграции WordPress-сайта. Надеюсь, этот материал поможет вам быстро и безопасно реализовать нужный функционал.