WordPress как на ладони
rgbcode is looking for WordPress developers. Очень Удобный и Быстрый Хостинг для сайтов на WordPress. Пользуюсь сам и вам рекомендую!

Глобальные параметры запроса

В REST API кроме частных параметров запроса для конкретного маршрута, есть глобальные параметры и параметры пагинации. А также некоторые тонкости связанные с параметрами запросов. Рассмотрим все это в этом разделе руководства.

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

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

_method (указание метода запроса)

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

Например, запросы на удаление используют метод DELETE, но некоторые клиенты не умеют отправлять этот метод. В этом случае метод можно указать в URL доаисав ?_method=DELETE или в заголовке запроса X-HTTP-Method-Override=DELETE и отправить 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 нужен для обеспечения поддержки всех браузеров.

Параметры пагинации/сортировки

На сайте может быть много контента и поэтому в REST API он делиться на части (за один запрос можно получить только часть контента). Конечные точки по умолчанию отдают ограниченное количество элементов на запрос. Аналогично тому, как выводятся 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.

1 комментарий
    Войти