Глобальні параметри запиту

У REST API, крім приватних параметрів запиту для конкретного маршруту, є глобальні параметри та параметри пагінації. Також деякі тонкощі пов’язані з параметрами запитів. Розглянемо це у цьому розділі керівництва.

Зміст:

Глобальні параметри

REST API має глобальні параметри (мета-параметри). Вони керують тим, як API обробляє запит/відповідь і працюють для всіх маршрутів і запитів. Усі такі параметри починаються з нижнього підкреслення _.

_method (вказівка методу запиту)

Коли сервер або клієнт не вміє надсилати нестандартний HTTP метод, метод можна вказати в параметрі _methodабо в заголовку запиту X-HTTP-Method-Override.

Наприклад, запити на видалення використовують DELETE , але деякі клієнти не вміють відправляти цей метод. У цьому випадку метод можна вказати в параметрі _methodабо в заголовку запиту X-HTTP-Method-Overrideі надіслати запит POST, а REST API обробить такий запит, як якщо б він був зроблений методом DELETE .

Для такого перевизначення методу підходить лише запит POST . Тому що GET запит може бути неправильно закешований.

Приклад перевизначення методу

POST http://example.com/wp-json/wp/v2/posts/42?_method=DELETE

Або вкажемо метод у header заголовках запиту:

POST /wp-json/wp/v2/posts/42 HTTP/1.1
Host: example.com
X-HTTP-Method-Override: DELETE

REST API обробить такі запити як DELETE ендпоінт.

_envelope (режим обгортки)

Коли клієнтська програма не вміє отримувати дані відповіді HTTP, їх можна передати в тілі відповіді (в JSON об’єкті), для цього потрібно встановити параметр _envelope . Так у тілі відповіді з’являться статус коду відповіді та інші заголовки (headers).

Для параметра не обов’язково вказувати значення його можна просто визначити. Тобто. можна просто додати ?_envelopeдо GET запит. Або можна вказати значення 1– ?_envelope=1якщо клієнтський додаток цього вимагає, результат буде однаковий.

_envelope відповідь містить не всі параметри header, тільки статус відповіді і деякі заголовки.

приклад

Відправимо звичайний запит:

GET http://example.com/wp-json/wp/v2/users/1

{
	"id": 1,
	"name": "kama",
	"url": "",
	"description": "",
	"link": "http://example.com/author/kama/",
	"slug": "kama",
	"avatar_urls": {
		"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g"
	}
}

Відправимо запит з ?_envelope :

GET http://example.com/wp-json/wp/v2/users/1?_envelope

{
	"id": 1,
	"name": "kama",
	"url": "",
	"description": "",
	"link": "http://example.com/author/kama/",
	"slug": "kama",
	"avatar_urls": {
		"24": "http://1.gravatar.com/avatar/155e695ab2251ee3c482c1e3e690683b?s=24&d=mm&r=g"
	},
	"status": 200,
	"headers": {
		"Allow": "GET"
	}
}

_embed (режим вбудовування)

Багато відповідей містять посилання пов’язані ресурси (маршурти), які розташовуються під ключом _links . Наприклад, пост може містити посилання на батьківську посаду або посилання на коментар до посту. Деякі з таких ресурсів можуть бути вбудовані, щоб зменшити кількість запитів HTTP. Так, клієнти можуть отримати сам ресурс, а також пов’язані з ним дані в одному запиті. Для цього потрібно вказати параметр ?_embed.

_embed переданий у GET запит включає режим вбудовування .

Для параметра не обов’язково вказувати значення його можна просто визначити. Тобто. можна просто додати ?_embedдо GET запит. Або можна вказати значення 1– ?_embed=1якщо клієнтський додаток цього вимагає.

Відповіді в режимі «вбудовування» будуть містити додатковий ключ _embedded, який міститиме дані пов’язаних ресурсів (маршрутів). Для того щоб вбудувався він повинен мати властивість embeddable = true .

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

_jsonp (крос-доменні запити)

REST API підтримує відповіді JSONP, щоб дозволити крос-доменні запити (між різними доменами) для застарілих браузерів та клієнтів. У цьому параметрі потрібно вказати назву функції зворотного дзвінка JavaScript. Відповідь буде обернено у вказану функцію, щоб потім URL можна було завантажити за допомогою тега <script> .

Функція зворотного дзвінка (значення параметра) може містити буквы, цифры, _або .: [a-zA-Z0-9_.]. Якщо вказати неправильне ім’я функції, то ми отримаємо відповідь з помилкою HTTP 400 і зворотний виклик не буде викликаний.

Приклад:

<script>
function receiveData( data ){
  // робимо щось із даними.
  // Виведемо дані в консоль.
  console.log(data);
}
</script>
<script src="https://demo.wp-api.org/wp-json/?_jsonp=receiveData"></script>

https://demo.wp-api.org/wp-json/?_jsonp=receiveDataповерне:

receiveData(
	{
		"name": "WP REST API Demo",
		"description": "Just another WP API Demo Sites site",
		"url": "https://demo.wp-api.org",
		"home": "https://demo.wp-api.org",
		"gmt_offset": "0",
		"timezone_string": "",
		"permalink_structure": "/%year%/%monthnum%/%day%/%postname%/",
		"namespaces": [
			"oembed/1.0",
			"broker/v1",
			"wp/v2"
		],
		...
	}
)

Для сучасних браузерів та програм параметр _jsonp не потрібен! Сучасні браузери можуть обробляти Cross-Origin Resource Sharing (CORS) запити для міждоменних запитів, а JSONP потрібен для забезпечення підтримки всіх браузерів.

Параметри пагінації/сортування

На сайті може бути багато контенту і тому в API REST він ділитися на частини (за один запит можна отримати тільки частину контенту). Кінцеві точки за промовчанням віддають обмежену кількість елементів на запит. Аналогічно, як виводяться 10 записів на одній сторінці рубрики.

У REST API також є пагінація, керується вона загальними параметрами, які можна вказати для маршрутів із колекціями елементів (що містять декілька елементів).

Параметри пагінації

?page=

Визначає, яку сторінку пагінації потрібно отримати.

Наприклад: /wp/v2/posts?page=2 поверне другу сторінку постів. Збираючи дані з ендпоінтів: /wp/v2/posts , /wp/v2/posts?page=2 і т.д. можна зібрати усі пости сайту.

?per_page=

Визначає, скільки елементів потрібно вивести на одній сторінці пагінації. Не може бути більше ніж 100.

Наприклад: /wp/v2/posts?per_page=1 отримає лише перший пост із усіх можливих.

?offset=

Визначає відступ (згори), з якого потрібно почати отримувати елементи.

Наприклад: /wp/v2/posts?offset=6 буде використовувати дефолтне кількість елементів на запит, але почне їх отримувати пропустивши 6 перших постів.

Об’єднання параметрів

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

/wp/v2/posts?per_page=5&page=4 – отримає 5 записів із 4 сторінки пагінації.
/wp/v2/posts?per_page=5&offset=15 – отримає 5 записів пропустивши 15. Це теж саме що й попередній варіант.

Великі запити можуть зменшити продуктивність сайту, тому per_pageобмежений 100 записами. Якщо потрібно отримати більше 100 записів, наприклад, для створення списку всіх доступних категорій, доведеться зробити кілька запитів і об’єднати результати в один.

Скільки даних всього

Щоб визначити, скільки всього існує сторінок даних, API повертає два поля у заголовках відповіді:

X-WP-Total: Загальна кількість записів у колекції
X-WP-TotalPages: Загальна кількість сторінок, що охоплюють усі доступні записи

Параметри сортування

REST API дозволяє сортувати результати за вказаними полями елемента. Для цього існує кілька параметрів:

?order=

Визначає, як сортувати. Може бути:

asc– зростання порядку – ?order=asc
desc– спадний порядок – ?order=desc

За замовчуванням: desc

?orderby=

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

/wp/v2/posts– author , date , id , include , modified , parent , relevance , slug , title .
/wp/v2/categories– id , include , name , slug , term_group , description , count

Для інших колекцій дивіться розділи отримання списку за маршрутом у розділі Маршрути WP з коробки .

За промовчанням: date (для всіх маршрутів елементи яких мають дати)

Чому параметри запиту не працюють?

Якщо параметри на зразок: ?page=2 або ?_embed ніяк не впливають на результат, це може означати, що ваш сервер налаштований якось інакше і не може їх визначити. Якщо для обслуговування запитів використовується Nginx, спробуйте знайти рядок try_files у конфігураційному файлі і якщо рядок виглядає так:

try_files $uri $uri/ /index.php$args;

то її потрібно змінити на:

try_files $uri $uri/ /index.php$is_args$args;

Змінна $is_args додасть знак ?, якщо є параметри запиту, це дозволить WordPress правильно визначити параметри запиту.

Що сталося із параметром запиту `?filter=` ?

Коли REST API було впроваджено в ядро WP, параметр запиту ?filter був видалений, щоб запобігти проблемам сумісності та обслуговування у майбутньому.

Можливість передавати аргументи фільтрації в параметрі ?filter , були потрібні на початку створення REST API (коли він був ще окремим плагіном). І майже всі параметри запиту були замінені більш стабільними: ?categories= , ?slug= і ?per_page= .

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

Повернути параметр запиту ?filter у REST API дозволяє плагін rest-filter .