REST API

WordPress REST API (або коротко WP API) дозволяє користувачам (HTTP Клієнтам) віддалено керувати сайтом, наприклад, отримувати/створювати пости, елементи таксономії, користувачів, коментарі і т.д. Робиться це через звичайні HTTP запити, звані «маршрути».
У відповідь на запит завжди повертається об’єкт JSON з даними.

REST API повноцінно був доданий до ядра WordPress у версії 4.7.

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

WordPress REST API (далі просто REST API або WP API) розроблений на базі технології REST, щоб мати зрозумілі URL-адреси та використовувати 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';

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

	// Параметри кінцевої точки (маршруту)
	$rout_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, $rout, $rout_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
}

Корисні посилання

• 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 (англ). Однак тут ми по можливості спрощуємо/уточнюємо/доробляємо/реструктуруємо контент, наводимо приклади і в результаті намагаємося подати інформацію зрозуміліше.