register_rest_route() │ WP 4.4.0

Реєструє маршрут REST API та його ендпоінти (кінцеві точки). Говорячи простіше реєструє URL по якому спрацьовуватиме вказана PHP функція.

Хуків немає.

Повертає

true|false. True у разі успіху та false при помилці.

Шаблон використання

add_action( 'rest_api_init', function () {

	register_rest_route( 'myplugin/v1', '/my_slug/(?P<param_name>.+)', array(
		'methods' => 'GET', // метод запиту: GET, POST ...
		'callback' => 'function_name', // функція обробки запиту. Повинна повернути відповідь на запит
		'permission_callback' => 'function_name', // функція перевірки доступу до маршруту. Повинна відновити true/false
		// опис параметрів, що передаються
		'args' => array(
			'param_name' => array(
				'default' => null, // значення параметра за замовчуванням
				'required' => null, // є параметр обов'язковим. Можливо тільки true
				'validate_callback' => 'function_name', // функція перевірки значення параметра. Повинна відновити true/false
				'sanitize_callback' => 'function_name', // функція очищення значення параметра. Повинна повернути очищене значення
			),
			'param_name2' => array(
				...
			)
			...
		),
	)));

} );

• Використання
  
  
  
• $namespace (рядок) (обов’язковий)
  
  
  
• $route (рядок) (обов’язковий)
  
  
  
• $args (масив)
  
  
  
• $override (логічний)
  
  
  
• Аргументи параметра $args
  
  
  
• methods (рядок/масив)
  
  
  
• callback (коллбек функція)
  
  
  
• permission_callback (коллбек функція) (обов’язковий)
  
  
  
• show_in_index (true/false)
  
  
  
• args (масив)
  
  
  
• description
  
  
  
• default
  
  
  
• required
  
  
  
• validate_callback
  
  
  
• sanitize_callback
  
  
  
• type
  
  
  
• minimum/maximum
  
  
  
• format
  
  
  
• enum
  
  
  
• Приклади
  
  
  

Використання

register_rest_route($namespace, $route, $args, $override);

$namespace
(рядок) (обов’язковий)

Перша частина маршруту (URL), яка йде після префіксу REST (
/wp-json/ ). Повинна бути унікальною, зазвичай тут використовується унікальна назва плагіна або теми, наприклад
myplugin/v1. Детальніше дивіться
простору імен у REST .

$route
(рядок) (обов’язковий)

Друга частина маршруту (URL). Підтримує регулярні висловлювання, наприклад
/author/(?P<id>d+).

$args
(масив)

Масив параметрів кінцевої точки.
За допомогою цих параметрів можна тонко налаштувати обробку запиту кінцевої точки.

Якщо потрібно створити кілька кінцевих точок, масив повинен містити вкладені масиви, в яких описується кожна кінцева точка.

Масив для однієї кінцевої точки за умовчанням виглядає так:

$args = [
	'methods' => 'GET',
	'callback' => null,
	'permission_callback' => null,
	'args' => array(),
];

Приклад як можна вказати кілька кінцевих точок (методів):

$args = [
	// common args
	'args' => [
		'id' => [
			'description' => __( 'Unique identifier for the term.' ),
			'type' => 'integer',
		],
	],
	// GET
	[
		'methods' => 'GET',
		'callback' => null,
		'permission_callback' => null,
		'args' => [],
	],
	// POST
	[
		'methods' => 'POST',
		'callback' => null,
		'permission_callback' => null,
		'args' => [],
	],
]

Опис усіх можливих аргументів дивіться нижче .

Створений тут масив, так само потрапляють у якість об’єкта WP_REST_Server::$endpoints .

$override
(логічний)

Визначає, чи потрібно переписати дані, якщо такий маршрут вже існує:

• true – перевизначити
• false – об’єднати за допомогою функції array_merge() .

Типово: false

Аргументи параметра $args

methods
(рядок/масив)

Визначає яким методом запиту, буде доступна кінцева точка: GET (за замовчуванням), POST, PUT, PATCH, DELETE. Декілька методів можна вказати рядком через кому або масивом.

Можна використовувати певні константи класу WP_REST_Server :

WP_REST_Server::READABLE // GET
WP_REST_Server::CREATABLE // POST
WP_REST_Server::EDITABLE // POST, PUT, PATCH
WP_REST_Server::DELETABLE // DELETE
WP_REST_Server::ALLMETHODS // GET, POST, PUT, PATCH, DELETE

callback
(коллбек функція)

Тут вказується ім’я функції, яка спрацьовуватиме при переході (запиті) на URL (rest маршрут). У функції потрібно сформувати та повернути дані. Повертаються дані будуть перетворені на json формат і виведені на екран.

У цьому параметрі, наприклад, можна використовувати свою функцію або іншу, яка повертає результат, наприклад get_posts() .

Функція зазначена у цьому параметрі як параметр отримує об’єкт класу WP_REST_Request , в ньому містяться параметри запиту і завдяки їм можна сформувати точну відповідь. Наприклад, якщо просто викликати get_posts() , вона поверне результат відповідно до її дефолтним налаштувань, але якщо її обернути на свою функцію і передати у виклик get_posts() отриманий параметр ID автора, можна відфільтрувати пости по автору (дивіться перший приклад).

Так як у функцію передається об’єкт класу WP_REST_Request , то доступні методи для отримання різної інформації:

// Реєструє маршрут
add_action( 'rest_api_init', function () {
	register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
		'methods' => 'GET',
		'callback' => 'my_rest_api_func',
	)));
} );

// Звернемося за адресою http://wp-test.ru/wp-json/myplugin/v1/author/1

function my_rest_api_func( WP_REST_Request $request ) {
	// Можна отримати доступ до параметрів через прямий доступ до масиву об'єкта:
	$param = $request['id']; // 1

	// Або за допомогою методу:
	$param = $request->get_param( 'id' ); // 1

	// Масив із усіх параметрів
	$parameters = $request->get_params(); // Array([id] => 1)

	// При необхідності також доступні окремі параметри параметрів:
	$parameters = $request->get_url_params(); // Array([id] => 1)

	$parameters = $request->get_query_params(); // Array()
	// Якщо запитати http://wp-test.ru/wp-json/myplugin/v1/author/1?post=1
	$parameters = $request->get_query_params(); // Array([post] => 1)

	$parameters = $request->get_body_params(); // Array()
	$parameters = $request->get_json_params(); // null - не було запиту із заголовком Content-type: application/json
	$parameters = $request->get_default_params(); // Array()

	// Дані про завантаження не об'єднані, але можуть бути доступні окремо:
	$parameters = $request->get_file_params();

	// варіанти повернення даних

	return new WP_REST_Response( true, 200 );

	return new WP_Error( 'no_author', 'Invalid author', array( 'status' => 404 ) );

	return 'рядок';

	return array('foo'=>'bar');

	// отримаємо об'єкт WP_REST_Response
	$response = rest_ensure_response( array( 'foo'=>'bar' ) );
	$ Response-> set_status (401);
	$response->set_headers([
		'X_REAL_IP' => '54.15.124.126',
	]);
	return $response;
}

permission_callback
(коллбек функція) (обов’язковий)

Дозволяє перевірити права користувача, який запитує маршрут. Доступ буде дозволено, якщо повернути true, та заборонено, якщо false.

З версії WordPress 5.5 цю функцію потрібно обов’язково вказувати!

Приклад, як дозволити доступ всім користувачам:

register_rest_route( 'myplugin/v1', '/awesome-route', array(
	'methods' => WP_REST_Server::READABLE,
	'callback' => 'my_awesome_func',
	'permission_callback' => '__return_true'
)));

Приклад, як перевірити можливості користувача:

register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
	'methods' => WP_REST_Server::READABLE,
	'callback' => 'my_awesome_func',
	'permission_callback' => 'my_awesome_permission_callback'
)));

function my_awesome_permission_callback ( WP_REST_Request $request ) {
	return current_user_can( 'edit_others_posts' );
}

Нехай функція my_awesome_func() повертає посади вказаного користувача. Якщо користувач має право змінювати чужі пости (наприклад, редактор), необхідні дані повернутися. Якщо таких прав у поточного користувача немає, то повернеться помилка:

{
	"code": "rest_forbidden",
	"message": "Вибачте, вам не дозволено виконувати цю дію.",
	"data": {
		"status": 401
	}
}

Така ж помилка повернеться, якщо не передати nonce , докладніше читайте у розділі Авторизація у WP REST API .

show_in_index
(true/false)

Чи потрібно показувати роут у схемі всіх роутів.

args
(масив)

Можливі параметри ендпоінту. Кожен елемент масиву визначає один параметр. Ключ елемента – це назва параметра запиту, а значення – це вкладений масив, який описує цей параметр.

Деякі дані параметра автоматично потрапляють у схему маршруту (наприклад , description , type , required …). Див. rest_get_allowed_schema_keywords() .

Можливі аргументи масиву:

description
default
required
sanitize_callback
validate_callback

// перевірка та очищення
type
	string
		minLength/maxLength
		pattern
		format
	null
	boolean
	number/integer
		minimum/maximum
		exclusiveMinimum / exclusiveMaximum
		multipleOf
	array
		items
		minItems/maxItems
		uniqueItems
	object
		properties
		additionalProperties
		patternProperties
		minProperties/maxProperties
enum
oneOf / anyOf

Типи даних REST. Перевірка та очищення – тут дивіться повний список можливих параметрів та їх опис.

• 
  description (рядок) (влучає у схему)
  Опис параметра.

• 
  default (різне) (влучає у схему)
  Значення за умовчанням для аргументу, якщо він не вказаний.

  register_rest_route( 'myplugin/v1', '/author/(?P<key>d+)', array(
  	'methods' => WP_REST_Server::READABLE,
  	'callback' => 'my_awesome_func',
  	'args' => array(
  		'key' => array(
  			'default' => 1
  		),
  	),
  )));

• 
  required (true/false) (потрапляє до схеми)
  Якщо в значенні вказати true і вказаний параметр не буде визначений (не буде вказано у запиті), то буде повернена помилка.

  Параметр у запиті повинен бути зазначений взагалі, щоб спрацювала ця настройка, тобто. якщо він зазначений, але у значенні його порожньо, то вважається, що він вказаний з порожнім значенням.

  required немає сенсу, якщо встановлено параметр default , оскільки аргумент завжди матиме значення.

  register_rest_route( 'myplugin/v1', '/author/(?P<key>d+)', array(
  	'methods' => WP_REST_Server::READABLE,
  	'callback' => 'my_awesome_func',
  	'args' => array(
  		'key' => array(
  			'required' => false // або true - обов'язковий параметр
  		),
  	),
  )));

• 
  validate_callback (рядок/callback)
  Функція перевірки даних. Функція повинна повертати true, якщо перевірка пройшла, і false інакше.

  Нехай функція my_awesome_func() повертає список постів вказаного автора, тоді:

  register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
  	'methods' => 'GET',
  	'callback' => 'my_awesome_func',
  	'args' => array(
  		'id' => array(
  			'validate_callback' => function($param, $request, $key) {
  				return is_numeric( $param );
  			},
  		),
  	),
  )));

  Запросимо записи автора з ID = 1 на адресу (припускаємо, що записи є):

  http://wp-test.ru/wp-json/myplugin/v1/author/1

  Повернеться масив із записами. Але якщо звернеться на адресу:

  http://wp-test.ru/wp-json/myplugin/v1/author/vasya

  То повернеться помилка:

  {
  	"code": "rest_no_route",
  	"message": "Відповідний маршрут для URL та методу запиту не знайдено",
  		"data": {
  		"status": 404
  	}
  }

  Тому що параметр id не пройшов перевірку функцій is_numeric (), оскільки значення не є числом.

  Здавалося б, чому просто не вказати функцію is_numeric() ось так:

  register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
  	'methods' => WP_REST_Server::READABLE,
  	'callback' => 'my_awesome_func',
  	'args' => array(
  		'id' => array(
  			'validate_callback' => 'is_numeric'
  		),
  	),
  )));
  

  Але, як можна помітити з прикладу вище, в зазначену функцію будуть передані три параметри $param, $request, $key і, якщо їх передати функції is_numeric() – буде помилка рівня warning.

  [29-May-2018 12:07:54 UTC] PHP Warning: is_numeric() expects exactly 1 parameter, 3 given in D:server72siteswp-test.ruwp-includesrest-apiclass- wp-rest-request.php on line 858

  Є тикет , який закликає це виправити, але поки що справа стоїть на місці.

• 
  sanitize_callback (рядок/callback)
  Функція очищення даних. Аналогічно validate_callback , тільки замість true/false потрібно повернути очищене вхідне значення. Або можна повернути об’єкт WP_Error .

  register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
  	'methods' => WP_REST_Server::READABLE,
  	'callback' => 'my_awesome_func',
  	'args' => array(
  		'id' => array(
  			'sanitize_callback' => function ( $param, $request, $key ) {
  				return (int) $param;
  			}
  		),
  	),
  )));

• 
  type (рядок) (входить у схему)
  Тип значення параметра. Можливі значення: array, object, string, number, integer, boolean, null. Якщо вказано інший тип, у відповідь видасть помилку 400. Докладніше про цей параметр .

• 
  minimum/maximum (число) (використовується у схемі)
  Мінімальне або Максимальне значення параметра. Тільки для type = integer .

• 
  format (рядок) (використовується у схемі)
  Додатковий формат рядка. Значення будуть перевірені на відповідність зазначеному формату. Докладніше .

  • date-time– Дата у форматі RFC3339 . див. rest_parse_date()
  • uri– uri відповідно до esc_url_raw() .
  • email– Див. is_email() .
  • ip– v4 або v6 адресу ip. rest_is_ip_address ()
  • uuid– uuid код будь-якої версії. wp_is_uuid ()
  • hex-color— 3 або 6 символів hex кольору у префіксі #. Див. rest_parse_hex_color() .
• 
  enum (масив) (використовується у схемі)
  Список можливих значення параметра (коли параметр обмежений список можливих значень).

Приклади

// Реєструє маршрут
add_action( 'rest_api_init', function () {

	register_rest_route( 'myplugin/v1', '/author/(?P<id>d+)', array(
		'methods' => 'GET',
		'callback' => 'my_awesome_func',
		'permission_callback' => '__return_true'
	)));
} );

// Обробляє запит
function my_awesome_func( WP_REST_Request $request ) {

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

	if (empty($posts))
		return new WP_Error( 'no_author_posts', 'Записів не знайдено', array( 'status' => 404 ) );

	return $posts;
}

http://wp-test.ru/wp-json/myplugin/v1/author/1

[
	{
		"ID": 280,
		"post_author": "1",
		"post_date": "2018-04-10 21:06:29",
		"post_date_gmt": "2018-04-10 18:06:29",
		"post_content": "Привіт! Ця стаття має стати винятком.rnrn[smr_slider id='1']",
		"post_title": "Ще стаття",
		"post_excerpt": "",
		"post_status": "publish",
		"comment_status": "open",
		"ping_status": "open",
		"post_password": "",
		"post_name": "eshhyo-statya",
		"to_ping": "",
		"pinged": "",
		"post_modified": "2018-05-25 11:34:03",
		"post_modified_gmt": "2018-05-25 08:34:03",
		"post_content_filtered": "",
		"post_parent": 0,
		"guid": "http://wp-test.ru/?p=280",
		"menu_order": 0,
		"post_type": "post",
		"post_mime_type": "",
		"comment_count": "0",
		"filter": "raw"
	},
	{
		"ID": 273,
		...
	}
	...
]

{
	"code": "no_author_posts",
	"message": "Записів не знайдено",
	"data": {
		"status": 404
	}
}

// Обробляємо запит
function my_awesome_func( WP_REST_Request $request ) {

	// Отримаємо записи вказаного автора
	$posts = get_posts(array(
		'author' => (int) $request['id'],
	)));

	if( empty( $posts ) )
		return new WP_Error( 'no_author_posts', 'Записів не знайдено', array( 'status' => 404 ) );

	// Створимо свої дані для повернення
	$posts = array_map( function ( $post ) {
		$post_data['title'] = esc_html( $post->post_title );
		$post_data['url'] = esc_url( get_the_permalink( $post ) );
		$post_data['comments'] = (int) $post->comment_count;
		$post_data['likes'] = (int) get_post_meta( $post->ID, 'likes', true );

		return $post_data;
	}, $ Posts);

	return $posts;
}

[
	{
		"title": "Ще стаття",
		"url": "http://wp-test.ru/eshhyo-statya",
		"comments": 3,
		"likes": 11
	},
	{
		"title": "Моя стаття",
		...
	},
	...
]

Додати свій приклад