Виявлення REST API

Виявлення – це будь-які дії, спрямовані на з’ясування того, як працює REST API. Наприклад:

Яким URL знаходиться кореневий каталог API.
Яку схему має ресурс?
Які параметри має певний ендпоінт.
Які плагіни/теми розширили (використовують) REST API.

Як правило, всі види виявлення зводяться до читання rest_url() .

Зміст:

Виявлення через Link у заголовку відповіді

Рекомендований шлях виявити URL на REST API це відправити HEAD запит на будь-яку сторінку сайту і перевірити чи є у відповіді параметр Link: . Rest API автоматично додає параметр Link до заголовків відповіді для всіх сторінок у фронтенді.

Link: <http://example.com/wp-json/>; rel="https://api.w.org/"

Вказане в параметрі посилання веде кореневий маршрут REST API ( /). Його можна використовуватиме подальшого виявлення маршрутів.

Для сайтів з відключеними ЧПУ /wp-json/автоматично не обробляється у WordPress. І в такому випадку посилання на REST API виглядатиме так:

Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"

Виявлення через `<link>` метатег

Для клієнтів, які не вміють читати HEADER заголовки відповіді (які парсят HTML або запускаються в браузері), URL на REST API можна отримати в HTML метатезі link в <head> частини документа. Такий метатег також додається всіх сторінках у вонтенде.

<link rel='https://api.w.org/' href='http://example.com/wp-json/' />

У Javascript це посилання можна отримати через DOM:

//jQuery варіант
var api_root = jQuery( 'link[rel="https://api.w.org/"]' ).attr( 'href' );

// Нативний JS
var links = document.getElementsByTagName( 'link' );
var link = Array.prototype.filter.call( links, function ( item ) {
	return item.rel === 'https://api.w.org/';
} );
var api_root = link[0].href;

Таке виявлення також справедливе виявлення Atom/RSS фидов. Таким чином, цей код можна адаптувати піт цю потребу.

Виявлення через RSD

Для клієнтів з підтримкою XML-RPC виявлення можливо зручніше буде отримати посилання на REST API через XML. Тут потрібно зробити два кроки:

Перший крок: знайти кінцеву точку (URL) RSD, вона розташована також у <link> елементі в <head> частини на будь-якій сторінці фронтенду:

<link rel="EditURI" type="application/rsd+xml" title="RSD" href="http://example.com/xmlrpc.php?rsd" />

Другий крок: отримати XML код за виявленим посиланням і розпарити його. Виглядає він приблизно так:

<?xml version="1.0" encoding="utf-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
  <service>
	<engineName>WordPress</engineName>
	<engineLink>https://wordpress.org/</engineLink>
	<homePageLink>http://example.com/</homePageLink>
	<apis>
	  <api name="WordPress" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
	  <!-- ... -->
	  <api name="WP-API" blogID="1" preferred="false" apiLink="http://example.com/wp-json/" />
	</apis>
  </service>
</rsd>

Елемент із посиланням на REST API завжди матиме атрибут name="WP-API".

RDS виявлення це НЕ рекомендований спосіб, тому що він найбільш складний, тут потрібно спочатку знайти посилання на RDS потім розпарсувати код за цим посиланням і тільки потім отримати URL самого REST API.

По можливості рекомендується уникати такого виявлення RDS!

Виявлення способів Авторизації

Виявлення також дозволяє дізнатися, які методи аутентифікації є в REST API. Відповідь головного маршруту API REST /wp-json/ містить об’єкт, який повністю описує API. У цьому об’єкті під ключем authenticationзнаходяться дані про можливі способи авторизації REST API:

{
	"name": "Example WordPress Site",
	"description": "YOLO",
	"routes": { ... },
	"authentication": {
		"oauth1": {
			"request": "http://example.com/oauth/request",
			"authorize": "http://example.com/oauth/authorize",
			"access": "http://example.com/oauth/access",
			"version": "0.1"
		}
	}
}

Докладніше про аутентифікацію в REST API читайте у відповідному розділі .

Виявлення наявних розширень

Після того, як REST API виявлено, потрібно дізнатися, що API підтримує. Дізнатися, які розширення є в API, можна з відповіді на кореневий маршрут REST API /wp-json/ . Там під ключом namespacesзнаходяться всі наявні розширення API:

Для WP версій від 4.4 до 4.6 доступні лише базове розширення oEmbed (повне API описане в цьому посібнику ще недоступне).

{
	"name": "Тестовий сайт",
	"namespaces": [
		"oembed/1.0/"
	]
}

З версії WP 4.7 доступно вже все API, так можна бачити нове розширення wp/v2 :

{
	"name": "Тестовий сайт",
	"namespaces": [
		"wp/v2",
		"oembed/1.0/"
	]
}

Перш ніж намагатись використовувати будь-яку з кінцевих точок, потрібно переконатися, що вона підтримується в API, для цього потрібно перевірити наявність потрібного простору імен, наприклад wp/v2 .

WordPress 4.4 включає інфраструктуру API для всіх сайтів, але не включає основні кінцеві точки під wp/v2 . Кінцеві точки ядра працюють із версією WordPress 4.7.

Цей же механізм можна використовувати для визначення підтримки розширень REST у плагінів. Наприклад, уявімо, що плагін реєструє наступний маршрут:

register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );

Тоді в даних API з’явиться нове розширення testplugin/v1 :

{
	"name": "Тестовий сайт",
	"namespaces": [
		"wp/v2",
		"oembed/1.0/",
		"testplugin/v1"
	]
}