REST API

WordPress REST API (или коротко WP API) позволяет пользователям (HTTP Клиентам) удаленно управлять сайтом, например получать/создавать посты, элементы таксономии, юзеров, комментарии и т.д. Делается все это через обычные HTTP запросы, так называемые «маршруты».
В ответ на запрос всегда возвращается JSON объект с данными.

Коротко о REST API (WP API)

WordPress REST API (далее просто REST API или WP API) разработан на базе технологии REST, чтобы иметь понятные URL-адреса и использовать коды HTTP ответов для указания успехов или ошибок. Использует встроенные функции HTTP, такие как http-аутентификация и http-команды (GET, POST), которые могут быть поняты многими HTTP-клиентами. WP API позволяет удобно и безопасно работать с WordPress из клиентского приложения.

REST API:

• Предоставляет структурированный, расширяемый и простой способ получить или передать данные в WordPress.

• Использует json в качестве формата запроса и ответа, включая ответы на ошибки.

• Предоставляет разные данные: публичные и приватные (доступны только после аутентификации). После аутентификации rest API позволяет управлять контентом сайта.

• Позволяет работать с любым языком программирования, который может обрабатывать HTTP-запросы и интерпретировать JSON, например Node.js или Java.

• Позволяет создать новые способы управления сайтом. К примеру, можно создать плагин, позволяющий администрировать сайт, или создать совершенно новый интерактивный интерфейс во фронэнде.

• Может заменить способ обработки ajax запросов. Смотрите: admin-ajax API.

При всей своей простоте, REST API может показаться сложным, поэтому изучение этой темы будет разбито на логические части, так будет проще освоить материал. В основном сложность заключается в новой терминологии — это всякие там ресурсы, эндпоинты, маршруты. Они нужны для создания и применения стандартов, но для понимания того, как это работает все эти вещи совсем не обязательны.

Создание маршрута

В WordPress, есть готовые маршруты. А также можно создавать свои собственные, для этого нужно использовать функцию register_rest_route().

Давайте создадим свой маршрут.

// создание маршрута
add_action( 'rest_api_init', function(){

	// пространство имен
	$namespace = 'myplugin/v1';

	// маршрут
	$route = '/author-posts/(?P<id>\d+)';

	// параметры конечной точки (маршрута)
	$route_params = [
		'methods'  => 'GET',
		'callback' => 'my_awesome_func',
		'args'     => [
			'arg_str' => [
				'type'     => 'string', // значение параметра должно быть строкой
				'required' => true,     // параметр обязательный
			],
			'arg_int' => [
				'type'    => 'integer', // значение параметра должно быть числом
				'default' => 10,        // значение по умолчанию = 10
			],
		],
		'permission_callback' => function( $request ){
			// только авторизованный юзер имеет доступ к эндпоинту
			return is_user_logged_in();
		},
	];

	register_rest_route( $namespace, $route, $route_params );

} );

// функция обработчик конечной точки (маршрута)
function my_awesome_func( WP_REST_Request $request ){

	$posts = get_posts( [
		'author' => (int) $request['id'],
	] );

	if ( empty( $posts ) ) {
		return new WP_Error( 'no_author_posts', 'Записей не найдено', [ 'status' => 404 ] );
	}

	return $posts;
}

Теперь пройдя по ссылке http://example.com/wp-json/myplugin/v1/author-posts/1 мы увидим JSON ответ, который вернула наша функция my_awesome_func().

Пояснения к коду:

• Маршрут нужно регистрировать именно на хуке rest_api_init, чтобы не выполнять никаких операций, если REST API отключен.

• Почему пространства имен называется именно myplugin/v1, читайте здесь.

• Маршрут /author-posts/(?P<id>\d+) указан как регулярное выражение для определения числа, чтобы по URL /author-posts/123 нам выдавались посты автора с ID 123.

• GET запрос на URL http://example.com/wp-json/myplugin/v1/author-posts/1 - это конечная точка, которую мы описали при регистрации маршрута.

  Маршрут может иметь несколько конечных точек, и для каждой конечной точки можно указать разные параметры:

  • methods — HTTP методы по которым нужно обращаться к конечной точке
  • callback — функцию обратного вызова для ответа на запрос
  • permission_callback — функцию обратного вызова для проверки права доступа к конечной точке.
  • args — параметры запроса, которые можно передать конечной точке. Каждый параметр описывается в виде элемента массива. Для каждого параметра можно указать свои опции, например, обязательный ли это параметр (required) или значение параметра по умолчанию (default), функцию проверки значения параметра (validate_callback). Подробнее читайте в разделе Типы параметров.

Ключевые понятия REST API

Смотрите в разделе Базовые знания REST API.

Нужно разобраться в каждом понятии, чтобы понимать что написано и о чем идет речь в этом руководстве!

Как узнать является ли текущий запрос REST запросом

Для этого можно проверить наличие константы REST_REQUEST:

if( defined('REST_REQUEST') ){
	// Это рест запрос
}

if( rest_get_url_prefix() === explode( '/', $_SERVER['REQUEST_URI'] )[1] ?? '' ){
	// this is rest request
}

SDK на PHP для удобной работы с WordPress REST API

https://github.com/madeITBelgium/WordPress-PHP-SDK

Библиотека устанавливается через composer. Пример использования:

use MadeITBelgium\WordPress\WordPressFacade as WP;

$users  = WP::post()->list();               // список постов
$result = WP::post()->create( $data );      // создать новый пост
$user   = WP::post()->get( $id );           // запись по ID
$result = WP::post()->update( $id, $data ); // обновить запись
$result = WP::post()->delete( $id );        // удалить запись

Полезные ссылки

• REST API Handbook (developer.wordpress.org)
• Использование WordPress REST API (learn.wordpress.org)
• Postman — Клиент для общения с WP API.
• REST API Handbook — официальное руководство по REST API (англ).
• Список изменений в REST API
• JSON Formatter — маленькое расширение для Chrome, чтобы удобно читать JSON ответы.
• JsonDiscovery — более мощное расширение для Chrome, чтобы удобно читать JSON ответы.
• Семинар по REST API (видео)
• WP REST API Changelog

--

Этот раздел создавался на базе официального руководства: REST API Handbook (англ). Однако тут мы по возможности упрощаем/уточняем/дорабатываем/реструктурируем контент, приводим примеры и в итоге стараемся подать информацию более понятно.