Что такое REST API и зачем он нужен?
REST (Representational State Transfer) API — это архитектурный стиль для создания веб-сервисов. WordPress REST API предоставляет стандартизированный интерфейс для взаимодействия с вашим сайтом WordPress из внешних приложений, таких как мобильные приложения, одностраничные веб-приложения (SPA), или другие веб-сервисы. Вместо генерации HTML на стороне сервера, API возвращает данные в формате JSON (JavaScript Object Notation), что делает их легко читаемыми и обрабатываемыми машинами.
Основное назначение REST API в WordPress — позволить разработчикам создавать и управлять контентом, пользователями и настройками сайта программно, без необходимости прямого взаимодействия с административной панелью WordPress. Это открывает возможности для создания более сложных и интегрированных решений.
Преимущества использования REST API в WordPress
Использование REST API дает несколько ключевых преимуществ:
Гибкость: Позволяет использовать WordPress как Headless CMS, где WordPress управляет контентом, а фронтенд может быть построен на любом фреймворке (React, Vue, Angular) или для нативных мобильных приложений.
Интеграция: Упрощает интеграцию WordPress с другими системами, CRM, ERP или сервисами автоматизации маркетинга.
Автоматизация: Позволяет автоматизировать задачи управления контентом, например, массовый импорт данных или синхронизацию продуктов из внешней базы данных.
Стандартизация: Предоставляет предсказуемый и документированный способ взаимодействия с WordPress.
Краткий обзор архитектуры REST API
WordPress REST API построен на основе стандартных HTTP-методов (GET, POST, PUT, DELETE) и эндпоинтов (URL-адресов), представляющих ресурсы WordPress (записи, страницы, пользователи, таксономии и т.д.).
Маршруты (Routes): URL-пути, определяющие доступные ресурсы. Например, /wp-json/wp/v2/posts.
Эндпоинты (Endpoints): Комбинация маршрута и HTTP-метода. Например, GET-запрос к /wp-json/wp/v2/posts — это эндпоинт для получения списка записей.
Запросы (Requests): HTTP-запросы, отправляемые клиентом к эндпоинту.
Ответы (Responses): Данные в формате JSON, возвращаемые сервером в ответ на запрос.
Базовый префикс для всех маршрутов API по умолчанию — /wp-json/.
Активация и настройка REST API в WordPress
Включено ли REST API по умолчанию?
Да, начиная с версии WordPress 4.7, REST API включен по умолчанию и не требует дополнительной активации для большинства стандартных операций чтения (GET-запросы к публичным данным).
Если вы используете более старую версию или хотите убедиться, что API активен, проверьте доступность основного эндпоинта вашего сайта, например https://yourdomain.com/wp-json/. Вы должны увидеть JSON-ответ со списком доступных маршрутов.
Настройка аутентификации REST API (базовая аутентификация, OAuth)
Для операций, изменяющих данные (POST, PUT, DELETE) или доступа к приватной информации, требуется аутентификация. WordPress поддерживает несколько методов:
Аутентификация по Cookie: Используется по умолчанию, когда вы вошли в систему WordPress в том же браузере. Подходит для тем и плагинов, работающих внутри WordPress.
Пароли приложений (Application Passwords): Рекомендуемый метод для внешних приложений и скриптов. Генерируются в профиле пользователя (Пользователи -> Профиль -> Пароли приложений). Каждый пароль используется для конкретного приложения и может быть отозван. Передается через заголовок Basic Auth.
Базовая аутентификация (Basic Authentication): Требует установки плагина (например, WP REST API Basic Auth). Передает логин и пароль пользователя в заголовке Authorization. Не рекомендуется для производственных сред без HTTPS, так как данные передаются в слабо зашифрованном виде (Base64).
OAuth (1.0a или 2.0): Стандартный протокол для авторизации сторонних приложений без передачи пароля пользователя. Требует установки плагинов (например, WP OAuth Server). Обеспечивает высокий уровень безопасности, но сложнее в настройке.
Выбор метода зависит от контекста использования API.
Разрешения и роли пользователей для REST API
Доступ к различным эндпоинтам и операциям контролируется системой ролей и прав WordPress. Например, для создания записи (POST /wp/v2/posts) пользователь должен иметь право edit_posts.
При аутентификации API использует права того пользователя, чьи учетные данные (или токен) были предоставлены. Для анонимных запросов используются права пользователя с ID 0 (гость).
Можно настраивать права доступа к стандартным и пользовательским эндпоинтам с помощью функции register_rest_route и параметра permission_callback.
<?php
/**
* Регистрирует кастомный REST API эндпоинт.
*/
add_action('rest_api_init', function () {
register_rest_route('myplugin/v1', '/data/(?P\d+)', [
'methods' => WP_REST_Server::READABLE, // Эквивалентно GET
'callback' => 'my_awesome_func',
// Проверка прав доступа
'permission_callback' => function (WP_REST_Request $request): bool {
// Разрешить доступ только администраторам
return current_user_can('manage_options');
},
]);
});
/**
* Функция обратного вызова для эндпоинта.
*
* @param WP_REST_Request $request Объект запроса.
* @return WP_REST_Response|WP_Error Ответ API.
*/
function my_awesome_func(WP_REST_Request $request): WP_REST_Response|WP_Error {
$param_id = (int) $request['id'];
// Логика получения данных по $param_id
$data = ['received_id' => $param_id, 'message' => 'Data fetched successfully'];
return new WP_REST_Response($data, 200);
}Использование REST API для получения данных
Основные эндпоинты WordPress REST API (записи, страницы, пользователи, медиа)
WordPress предоставляет множество встроенных эндпоинтов для доступа к основным типам контента:
/wp/v2/posts: Записи блога.
/wp/v2/pages: Страницы.
/wp/v2/media: Файлы медиабиблиотеки.
/wp/v2/users: Пользователи.
/wp/v2/categories: Рубрики.
/wp/v2/tags: Метки.
/wp/v2/comments: Комментарии.
/wp/v2/taxonomies: Зарегистрированные таксономии.
/wp/v2/types: Зарегистрированные типы записей.
Полный список доступных эндпоинтов можно получить, отправив GET-запрос к корню API (/wp-json/).
Примеры запросов GET к REST API (с использованием cURL, JavaScript)
cURL (командная строка): Получение последних 5 записей.
# Запрос без аутентификации к публичным данным
curl https://yourdomain.com/wp-json/wp/v2/posts?per_page=5
# Запрос с использованием Application Password
curl --user "username:xxxx xxxx xxxx xxxx xxxx xxxx" https://yourdomain.com/wp-json/wp/v2/users/meJavaScript (Fetch API): Получение списка страниц и вывод их заголовков.
/**
* Асинхронно получает список страниц WordPress и выводит их заголовки.
*
* @param {string} apiUrl Базовый URL WordPress REST API (например, 'https://yourdomain.com/wp-json/').
*/
async function fetchWordPressPages(apiUrl) {
const pagesEndpoint = `${apiUrl}wp/v2/pages?_fields=id,title`; // Запрашиваем только ID и заголовок
try {
const response = await fetch(pagesEndpoint);
if (!response.ok) {
throw new Error(`HTTP error! Status: ${response.status}`);
}
const pages = await response.json();
console.log('Fetched Pages:');
pages.forEach(page => {
// Пример простой обработки: вывод заголовка
console.log(`- ${page.title.rendered}`);
});
// Пример псевдо-анализа: подсчет среднего количества слов в заголовках
if (pages.length > 0) {
const totalWords = pages.reduce((sum, page) => {
return sum + page.title.rendered.split(' ').length;
}, 0);
const avgWords = totalWords / pages.length;
console.log(`\nAverage words per title: ${avgWords.toFixed(2)}`);
}
} catch (error) {
console.error('Error fetching WordPress pages:', error);
}
}
// Вызов функции
fetchWordPressPages('https://yourdomain.com/wp-json/');Фильтрация и сортировка данных в запросах REST API
API позволяет уточнять выборку данных с помощью параметров URL:
per_page: Количество элементов на странице ответа.
page: Номер страницы для пагинации.
search: Поиск по ключевому слову.
orderby: Поле для сортировки (date, id, title, slug и др.).
order: Направление сортировки (asc или desc).
filter: Устарел, но все еще может работать. Предпочтительнее использовать специфичные параметры.
categories, tags: Фильтрация записей по ID рубрик или меток.
slug: Получение объекта по его ярлыку.
author: Фильтрация записей по ID автора.
_fields: Позволяет указать, какие поля включить в ответ, уменьшая его объем.
Пример: Получить 3 самые старые записи из рубрики с ID 5.
GET /wp-json/wp/v2/posts?categories=5&per_page=3&orderby=date&order=asc
Работа с метаданными через REST API
По умолчанию, метаданные записей (post meta) не включаются в ответы API для стандартных эндпоинтов. Чтобы работать с ними, необходимо зарегистрировать их для отображения в REST API с помощью функции register_post_meta или register_meta.
true, // Показать в REST API
'single' => true, // Ожидается одно значение
'type' => 'string', // Тип данных
'auth_callback' => function() { // Опционально: проверка прав на изменение/чтение
return current_user_can('edit_posts');
}
]);
});После регистрации метаполе появится в объекте meta ответа API для соответствующей записи, и его можно будет читать и обновлять через API.
Управление данными через REST API (POST, PUT, DELETE)
Для выполнения этих операций требуется аутентификация с соответствующими правами.
Создание новых записей и страниц с использованием REST API
Используется метод POST к эндпоинту коллекции (например, /wp/v2/posts). Данные передаются в теле запроса в формате JSON.
Пример (cURL): Создание новой записи.
curl -X POST https://yourdomain.com/wp-json/wp/v2/posts \
--user "username:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{
"title": "Новая запись из API",
"content": "Это контент новой записи, созданной через REST API.",
"status": "publish",
"categories": [5]
}'Обновление существующих данных через REST API
Используется метод POST или PUT к эндпоинту конкретного ресурса (например, /wp/v2/posts/<id>). PUT обычно подразумевает полную замену ресурса, POST (или PATCH, если поддерживается) — частичное обновление.
Пример (cURL): Обновление заголовка записи с ID 123.
curl -X POST https://yourdomain.com/wp-json/wp/v2/posts/123 \
--user "username:xxxx xxxx xxxx xxxx xxxx xxxx" \
-H "Content-Type: application/json" \
-d '{"title": "Обновленный заголовок записи"}'Удаление контента с помощью REST API
Используется метод DELETE к эндпоинту конкретного ресурса.
Пример (cURL): Удаление записи с ID 123 (перемещение в корзину).
curl -X DELETE https://yourdomain.com/wp-json/wp/v2/posts/123?force=false \
--user "username:xxxx xxxx xxxx xxxx xxxx xxxx"Параметр force=true удалит запись навсегда, минуя корзину.
Обработка ошибок и валидация данных
REST API возвращает стандартные HTTP-статус коды для индикации результата операции:
200 OK: Успешный GET, PUT, POST (обновление).
201 Created: Успешное создание ресурса (POST).
400 Bad Request: Ошибка в запросе (неверные параметры, некорректный JSON).
401 Unauthorized: Ошибка аутентификации.
403 Forbidden: Аутентификация прошла, но у пользователя нет прав на операцию.
404 Not Found: Ресурс не найден.
500 Internal Server Error: Ошибка на сервере.
В случае ошибки API обычно возвращает JSON-ответ с полями code, message и data для дополнительной информации.
{
"code": "rest_post_invalid_id",
"message": "Недопустимый ID записи.",
"data": { "status": 404 }
}Валидация данных, передаваемых в POST/PUT запросах, происходит на стороне сервера. Можно добавлять свои правила валидации для стандартных и кастомных эндпоинтов.
Расширение REST API WordPress
Создание собственных эндпоинтов REST API
Вы можете создавать собственные маршруты и эндпоинты для специфических нужд вашего приложения или интеграции. Используется функция register_rest_route внутри хука rest_api_init.
Пример: Создание эндпоинта для получения данных о рекламной кампании.
<?php
/**
* Регистрирует кастомный REST API маршрут для данных кампании.
*/
add_action('rest_api_init', function () {
register_rest_route('my-marketing/v1', '/campaign/(?P[a-zA-Z0-9-]+)', [
'methods' => WP_REST_Server::READABLE, // GET
'callback' => 'get_marketing_campaign_data',
'permission_callback' => '__return_true', // Доступен всем (можно ограничить)
'args' => [
'campaign_slug' => [
'validate_callback' => function($param, $request, $key) {
return is_string($param) && !empty(trim($param));
},
'sanitize_callback' => 'sanitize_key',
'required' => true,
'description' => 'Идентификатор кампании (slug).',
],
],
]);
});
/**
* Получает данные для указанной маркетинговой кампании.
*
* @param WP_REST_Request $request Запрос.
* @return WP_REST_Response|WP_Error Ответ или ошибка.
*/
function get_marketing_campaign_data(WP_REST_Request $request): WP_REST_Response|WP_Error {
$slug = $request['campaign_slug'];
// Здесь должна быть логика получения данных кампании,
// например, из кастомной таблицы или CPT.
// В этом примере возвращаем статичные данные.
$campaign_data = [
'slug' => $slug,
'source' => 'google_ads',
'clicks' => rand(100, 1000), // Пример случайных данных
'conversions' => rand(5, 50),
];
if (empty($campaign_data)) {
return new WP_Error('campaign_not_found', 'Кампания не найдена', ['status' => 404]);
}
return new WP_REST_Response($campaign_data, 200);
}Использование плагинов для расширения REST API
Многие популярные плагины (WooCommerce, ACF, Yoast SEO и др.) предоставляют собственные эндпоинты для взаимодействия с их данными через REST API. Это значительно расширяет возможности интеграции.
Существуют также плагины, упрощающие создание кастомных эндпоинтов или модификацию существующих без написания кода.
Безопасность при разработке собственных эндпоинтов
При создании кастомных эндпоинтов крайне важно уделять внимание безопасности:
Аутентификация и авторизация: Всегда используйте permission_callback для проверки прав доступа. Не оставляйте эндпоинты, изменяющие данные, открытыми для анонимных пользователей.
Валидация и санация данных: Тщательно проверяйте (validate_callback) и очищайте (sanitize_callback) все входящие параметры, чтобы предотвратить XSS, SQL-инъекции и другие атаки.
Нонсы (Nonces): Для запросов, инициируемых из админ-панели или фронтенда аутентифицированным пользователем, используйте нонсы для защиты от CSRF-атак.
HTTPS: Всегда используйте HTTPS для шифрования трафика API, особенно при передаче учетных данных.
Ограничение скорости запросов (Rate Limiting): Рассмотрите возможность внедрения ограничения скорости для защиты от DoS-атак.