Зміна відповідей робочих ендпоінтів

Іноді можуть виникнути ситуації, коли потрібно змінити відповіді робочих ендпоінтів. Наприклад, додати або видалити дані до них. Логіка роботи WP API дозволяє це зробити без особливих складнощів.

У цьому посібнику описано, як додати додаткові дані у відповіді ендпоінтів. А також описується, як доповнити ключ _links і як створити свій компактний URL (CURIE) у такому _links ключі.

Зміст:




Додавання свого поля у відповідь REST API

Важливе зауваження щодо зміни відповідей REST API

Зміна даних відповіді небезпечна! А додавання даних у відповідь безпечне!

API видає багато полів у відповідях і багато хто з них вам може бути не потрібний. Звідси може виникнути спокуса змінити або видалити поля з відповідей REST API. Але робити цього не можна, тому що інші Клієнти чекають на стандартні відповіді. І одним із таких Клієнтів є сама адмінка WordPress.

Тому зміна або видалення даних відповіді кінцевої точки ядра WordPress заборонено!

Як змінити відповідь якщо дуже треба?

Якщо вам все ж таки дуже потрібно змінити якісь дані відповіді, то варіантів може бути кілька:

  • Можна дублювати поле зі зміненими даними.
  • Або можна створити параметр запиту, при вказівці якого непотрібні поля будуть видалятися з відповіді.
  • Або можна працювати з контекстами, наприклад створити свій контекст, який повертатиме лише потрібні поля.

Як бачите, є багато варіантів змінити дані відповіді, не зашкодивши спільній роботі API, користуйтеся ними!

Існують дві функції, які дозволяють додати дані (поля) у відповідь REST API:

Докладніше про те, як працюють функції, читайте в їх описі і нижче дивіться приклади додавання полів.

Обидві ці функції підійдуть для будь-якого ресурсу REST API (пост, термін…) та будь-якого методу запиту (GET POST).

Недолік register_meta() у цьому, що функція розуміє лише скалярні значення, а register_rest_field() може обробити об’єкти.




register_rest_field( $object_type, $attribute, $args )

register_rest_field() додає довільне поле для зазначеного ресурсу REST API.

$object_type
(рядок/масив) (обов’язковий)
Назва ресурсу REST для якого реєструється поле. Декілька ресурсів можна вказати в масиві. Можливі ресурси з ядра:
post ,
term ,
meta ,
user ,
comment . Також може бути назва довільного ресурсу, наприклад, при реєстрації типу запису або таксономії.
$attribute
(рядок) (обов’язковий)
Назва поля. Це поле буде використано як ключ в об’єкті відповіді REST.
$args
(масив)
Параметри обробки вказаного поля під час запиту REST.

  • $get_callback (рядок/масив/null)
    Функція отримання значення поля.
    Типово: null – значення не буде показано у відповіді
  • $update_callback (рядок/масив/null)
    Функція, яка використовується для встановлення та оновлення значення поля.
    Типово: null – значення не може бути встановлене або оновлено
  • $schema (рядок/масив/null)
    Функція, яка використовується для створення схеми цього поля.
    Типово: null – схема не буде показана

За замовчуванням: array()

приклад

Створимо можливість читати та записувати метаполі у REST запиті для коментарів.

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

Це демонстраційний приклад, який показує, які перевірки дозволів або обробка помилок можуть знадобитися для поля.

// Реєструвати поле потрібно під час події 'rest_api_init'!
add_action( 'rest_api_init', function () {

	// реєструємо REST поле
	register_rest_field( 'comment', 'karma', array(

		// функція виведення значення поля за відповіді
		'get_callback' => function( $comment_arr ) {
			$ comment_obj = get_comment ($ comment_arr ['id']);
			return (int) $comment_obj->comment_karma;
		},

		// функція оновлення поля
		'update_callback' => function( $karma, $comment_obj ) {
			$ ret = wp_update_comment (array (
				'comment_ID' => $comment_obj->comment_ID,
				'comment_karma' => $karma
			)));

			if (false === $ret) {
				return new WP_Error( 'rest_comment_karma_failed', __( 'Failed to update comment karma.' ), array( 'status' => 500 ) );
			}
			return true;
		},

		// Опис поля у схемі
		'schema' => array(
			'description' => __( 'Comment karma.' ),
			'type' => 'integer'
		),

	)));

} );




register_meta( $object_type, $meta_key, $args )

register_meta() реєструє метаполе. Якщо при реєстрації метаполя вказати параметр show_in_rest = true , це поле буде доступне в REST API і буде відображатися у відповіді в ключі meta . Також це метаполі можна буде створювати/оновлювати через запит REST.

$object_type
(рядок) (обов’язковий)
Тип об’єкта якого реєструється метаполі:
post,
user,
comment,
term. Параметр
$meta_type з функцій
{add/get/update/delete}_metadata( $meta_type, …)
$meta_key
(рядок) (обов’язковий)
Назва ключа, що реєструється.
$args
(масив) (обов’язковий)
Дані описують метаполі. За замовчуванням такі:

$ args = array (
	'object_subtype' => '',
	'type' => 'string',
	'description' => '',
	'single' => false,
	'sanitize_callback' => null,
	'auth_callback' => null,
	'show_in_rest' => false,
);

register_meta() це загальна функція, для неї є обгортки, щоб зручно реєструвати метаполі для записів та елементів таксономій:

приклад

Цей приклад показує, як створити поле, яке можна буде читати, створювати та оновлювати в REST API.

Оновлення поля буде доступне за запитом: POST wp-json/wp/v2/posts/ .

Примітка: якщо під час реєстрації типу запису в параметріsupports не зазначено властивість custom-fields , то мета-поля не відображатимуться в rest API.

// Реєстрація метаполя для типу запису 'post' із підтримкою REST API
register_post_meta( 'post', 'my_meta_key', array(
	// Тип поля, можливо: 'string', 'boolean', 'integer', 'number'.
	// Вказаний тип використовується для очищення поля при записі та виведенні.
	'type' => 'string',
	// опис буде показано у схемі ключа.
	'description' => 'A meta key associated with a string meta value.',
	// метаполі може мати лише одне значення.
	'single' => true,
	// використовувати поле в WP REST API
	'show_in_rest' => true,
)));




Додавання _links у відповідь API

WordPress генерує список посилань, пов’язаних із запитуваним ресурсом, щоб спростити навігацію до пов’язаних ресурсів. Докладніше тут .

{
 "_links": {
	"self": [
	  {
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/posts/28312"
	  }
	],
	"collection": [
	  {
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/posts"
	  }
	],
	"author": [
	  {
		"embeddable": true,
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/users/8670591"
	  }
	],
	"replies": [
	  {
		"embeddable": true,
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/comments?post=28312"
	  }
	],
	"wp:term": [
	  {
		"taxonomy": "category",
		"embeddable": true,
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/categories?post=28312"
	  },
	  {
		"taxonomy": "post_tag",
		"embeddable": true,
		"href": "https://make.wordpress.org/core/wp-json/wp/v2/tags?post=28312"
	  }
	]
  }
}

Ключ _links в JSON об’єкті не міститься в WP_REST_Response::$data і до нього немає доступу через WP_REST_Response::get_data() , тому що цей ключ додається прямо перед тим, як повернути відповідь.

Довільне посилання може бути додано через метод:

WP_REST_Response::add_link( $rel, $href, $attributes )

$rel
(рядок)
Зв’язок посилання. Повинен бути рядок із
доступного списку IANA . Або можна вказати URL адресу зареєстровану як «Компактин URL (CURIE)». Приклад CURIE:
https://api.w.org/term перетворитися на
wp:term під час створення відповіді API.
$href
(рядок)
URL-адреса посилання.
$attributes
(масив)
Список атрибутів посилання. Тут може бути різні параметри (залежить від контролера ресурсу).

  • embeddable– Включає підтримку _embed . Якщо кілька посилань додаються з однаковим зв’язком, то вбудовування будуть у тому порядку, в якому були додані посилання.

Приклади додавання посилання:

$response->add_link( 'author', rest_url( "/wp/v2/users/{$post->post_author}" ) );

$response->add_link( 'https://api.w.org/term', add_query_arg( 'post', $post->ID, rest_url( "/wp/v2/{$tax_base}" ) ) ));

$response->add_link( 'author', rest_url( "/wp/v2/users/{$post->post_author}" ), array(
	'embeddable' => true,
)));

$response->add_link( 'author', rest_url( "/wp/v2/users/{$additional_author}" ), array(
	'embeddable' => true,
)));

Приклад реалізації посилань на публікації із кількома авторами. Порядок додавання посилань зберігається.

{
  "_links": {
	"author": [
	  {
		"embeddable": true,
		"href": "https://yourwebsite.com/wp-json/wp/v2/users/1"
	  },
	  {
		"embeddable": true,
		"href": "https://yourwebsite.com/wp-json/wp/v2/users/2"
	  }
	]
  },
  "_embedded": {
	"author": [
	  {
		"id": 1,
		"name": "Primary Author"
	  },
	  {
		"id": 2,
		"name": "Secondary Author"
	  }
	]
  }
}




Реєстрація свого Компактного URL (CURIE)

CURIEs – “Compact URIs” – URL записується в компактному вигляді, щоб зрозуміло та універсально виглядати у відповіді API. Поняття було запроваджено з версії WP 4.5.

Приклад CURIE: https://api.w.org/term перетворитися на wp:term під час створення відповіді API.

Усі варіанти:

https://api.w.org/items = wp:items
https://api.w.org/featuredmedia = wp:featuredmedia
https://api.w.org/attachment = wp:attachment
https://api.w.org/term = wp:term
https://api.w.org/post_type = wp:post_type

Свої CURIEs можна додати через фільтр rest_response_link_curies .

Наприклад, зробимо перетворення посилання https://api.mypluginurl.com/my_link у my_plugin:my_link у відповіді API.

add_filter( 'rest_response_link_curies', 'my_plugin_prefix_register_curie');
function my_plugin_prefix_register_curie( $curies ) {

	$curies[] = array(
		'name' => 'my_plugin',
		'href' => 'https://api.mypluginurl.com/{rel}',
		'templated' => true,
	);

	return $curies;
}

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *