WP REST API - получение данных

В предыдущих частях серии мы рассмотрели, что такое WP REST API и как он может помочь нам в создании приложений для бекэнда WordPress.

Также мы рассмотрели два варианта настройки аутентификации для генерации аутентифицированных запросов: базовый и OAuth 1.0a.

Теперь, когда мы научились настраивать аутентификацию, мы готовы к генерации запросов и раскрытию мощи WP REST API. Мы будет использовать базовую аутентификацию, так как она проще, но для живых сайтов конечно же необходимо использовать OAuth 1.0a.

В этой части серии мы будем:

• анализировать структуру GET запроса;
• проверять, как запрос OPTIONS само-документирует API;
• отправлять запросы на сервер для получения данных;
• анализировать ответ сервера, который включает в себя свойства, схему и ссылки.

Давайте начнём с анализа структуры GET запроса.

Анатомия GET запроса

Перед тем как погрузиться в детали получения данных через WP REST API, мы должны ознакомиться с синтаксисом запроса, который посылается на сервер. Это послужит прочным фундаментом для нашего дальнейшего взаимодействия с WP REST API.

Рассмотрим следующий запрос на сервер:

GET http://localserver/wp-json/wp/v2/posts

Тип отправленного запроса – это GET, один из шести HTTP глаголов, которые мы рассмотрели в начале серии материалов. Запрос GET используется для получения данных с сервера. Когда он выполняется на сервере, то получает коллекцию объектов постов в форме JSON данных.

Мы можем разбить URL на следующие части:

• http://localserver/: URL локального сервера разработки. Это может быть любой адрес, в зависимости от того, где установлен WordPress .;
• /wp-json: это префикс конечной точки WP REST API;
• /wp: пространство имён плагина WP REST API;
• /v2: версия плагина WP REST API;
• /posts: это ресурс, который мы хотим получить с сервера.

Пространство имён предотвращает оверрайд, который может возникнуть при использовании нескольких плагинов, каждый из которых предоставляет свой слой абстракции для RESTful API.

В дополнение к получению коллекции ресурсов (постов), используя этот же URI, мы можем получить конкретный ресурс, указав его ID:

GET /wp/v2/posts/100

Запрос выше вернёт объект поста, так как он ищет ресурс поста с ID равным 100.

Теперь, когда мы изучили запрос GET, мы можем перейти к запросу OPTIONS. Запрос OPTIONS позволяет легко делать обход по API, и в принципе служит своего рода само-документированным способом, который делает API более доступным путём документирования всех доступных методов HTTP и их аргументов в конечной точке.

Освоение API при помощи запроса OPTIONS

Запрос OPTIONS может быть чрезвычайно полезен для освоения API. Он упоминает все конечные точки, которые принадлежат определённому пути, и предоставляет список параметров, CRUD операции которых поддерживают эти конечных точки.

Давайте отправим запрос OPTIONS по пути /wp/v2/posts для проверки того, какие конечные точки он поддерживает и какие параметры мы можем передать вместе с запросом GET для получения данных:

curl -X OPTIONS wp/v2/posts

Получаем ответ:

{
    "namespace": "wp/v2",
    "methods": [...],
    "endpoints": [...],
    "schema": {...},
    "_links": {...}
}

Итак, запрос к OPTIONS по пути /wp/v2/posts возвращает нам данные в формате JSON, и содержит 5 свойств:

1.namespace

2.methods

3.endpoints

4.schema

5._links

{
    "namespace": "wp/v2",
    ....
}

Свойств namespace определяет пространство имён текущего плагина. В нашем случае это wp/v2, то есть WP REST API версии 2.

{
    ...
    "methods": [
        "GET",
        "POST"
    ],
    ...
}

Свойство methods содержит массив всех методов, которые поддерживает текущий путь. Мы видим, что путь /wp/v2/posts поддерживает два метода: GET и POST. Это значит, что мы можем использовать этот путь для получения постов и их создания.

Следующее свойство endpoints содержит массив всех поддерживаемых конечных точек для текущего пути. Свойство напрямую связано со свойством methods, так как показывает список всех конечных точек для поддерживаемых методов.

{
    ...
    "endpoints": [
        {
            "methods": [
                "GET"
            ],
            "args": {...}
        },
        {
            "methods": [
                "POST"
            ],
            "args": {...}
        }
    ],
    ...
}

Свойство endpoints содержит два объекта значения, которые содержат два свойства methods and args. Свойство methods содержит массив HTTP методов, а свойство args содержит все поддерживаемые этими методами аргументы. Это те аргументы, которые мы переедаем вместе с запросом в форме параметров URI.

Смотря на аргументы, которые поддерживает метод GET, мы приходим к девяти аргументам, таким как context, page, per_page и другим. Эти объекты аргументов содержат два свойства required и default. Свойство required означает, что аргумент обязателен, а свойство default представляет собой значение по умолчанию этого аргумента.

"methods": [
        "GET"
    ],
"args": {
    "context": {
        "required": false,
        "default": "view"
    },
    "page": {
        "required": false,
        "default": 1
    },
    "per_page": {
        "required": false,
        "default": 10
    },
    "filter": {
        "required": false
    }
}

Свойство schema документирует все свойства текущего ресурса. Она определяет структуру данных формата JSON. Формат, используемый в WP REST API, основывается на draft 4 спецификации схемы JSON.

Последнее свойство _links включает в себя массив объектов, которые содержат ссылки на ассоциированные ресурсы. Ключ в объекте обозначает тип связи (например author, collection, self, comments, и т.д.), а значение является ссылокой на этот ассоциированные ресурс. Эти стандарты основываются на HAL (Hypertext Application Language).

По аналогии мы можем отправить запрос OPTIONS по другим путям, включая users, comments, media, pages и т.п., для проверки поддерживаемых методов и аргументов. Запрос OPTIONS это ваш лучший друг при работе с WP REST API.

WP REST API предоставляет ещё один путь для получения возможностей API, через GET запрос по пути /wp-json. Он отобразит список всех путей и их конечных точек вместе с поддерживаемыми методами и аргументами.

curl -X GET http://wordpress-server/wp-json

Ниже результат запроса:

Это поможет нам в будущем при работе над CRUD операциями.

Теперь, когда мы рассмотрели наши пути навигации по API, давайте начнём работу с WP REST API для получения данных от сервера.

Работа с постами (Posts)

Итак, мы ознакомились с запросом OPTIONS и готовы применить полученные знания для получения различных ресурсов с сервера, используя WP REST API.

А начнём мы с ресурса постов (Posts), так как это основополагающий блок WordPress. Используя эти знания, вы сможете запрашивать посты с помощью WP REST API так же, как вы делаете это с помощью класса WP_Query().

В предыдущих частях серии мы уже работали с постами и рассматривали примеры запросов для получения коллекций постов и индивидуального поста по его ID. Поэтому мы не будем это рассматривать повторно, а вместо этого коснёмся более продвинутых путей получения постов при помощи параметров топ-уровня.

Работы с параметрами топ-уровня

WP REST API раскрывает некоторые наиболее часто используемые переменные запросов непосредственно в конечной точке GET. Это параметры:

1. context: область запроса. Возможные значения: view, embed или edit.
2. page: текущая страница коллекции постов.
3. per_page: общее кол-во постов на страницу.
4. search: поисковой запрос. Ограничивает результат по совпадающей строке.
5. author: ID автора. Используется для ограничения результата по конкретному автору.
6. exclude: массив ID постов, которые должны быть исключены из результата.
7. include: массив ID постов, которые должны быть включены в результат.
8. offset: сдвигает поисковой результат по указанному значению.
9. order: порядок коллекции: asc или desc.
10. orderby: атрибут сортировки коллекции: id, title или slug.
11. slug: ограничивает результат постом, который имеет конкретный slug.
12. status: используется для ограничения результат по статуса постов.

Параметр context используется для получения постов в зависимости от области, в которой мы работаем. Если мы просто листаем посты на какой-то странице, то достаточно контекста view. Но если мы получаем посты, чтобы их редактировать, тогда нужно использовать контекст edit:

GET /wp/v2/posts?context=edit

Параметр контекста edit вводит новое поле raw, по типу title, content, excerpt. Значение этого поля может быть выведено в редактор для редактирования контента.

Использование контекста edit требует от вас аутентификации с привилегией edit_posts.

Используя значение embed контекста, мы получаем коллекцию постов с минимальным набором свойств.

Другие параметры говорят сами за себя, так что вы можете сами поиграться с ними в вашем HTTP-клиенте.

Это были базовые параметры для получения постов по определённым критериям.

Работа с Post Revisions, Categories, Tags и Meta

Ревизии постов позволяют просмотреть и восстановить редакции, сделанные в посте. WP REST API позволяет просматривать все ревизии через запрос к конечной точке /posts/<id>/revisions:

GET /wp/v2/posts/10/revisions

Запросы выше возвратит массив, содержащий объекты ревизий:

Конкретная ревизия может быть получена по ID:

GET /wp/v2/posts/10/revisions/2

Получение категорий конкретного поста возможно через следующий запрос:

GET /wp/v2/categories?post=<post_id>

Похожим запросом можно получить теги поста:

GET /wp/v2/tags?post=<post_id>

Здесь  <post_id> - это ID поста.

Для получения meta для поста с ID равным 10, мы отправляем следующий запрос:

GET /wp/v2/posts/10/meta

Запрос вернёт массив мета объектов.

Работа с другими ресурсами

Итак, мы уже получили достаточно солидную базу по работе с WP REST API по получению данных. Мы рассмотрели на запрос OPTIONS, который помогает раскрыть API без обращения к внешней документации. Вы всегда можете отправить этот запрос к конкретному ресурсу и узнать его возможности. Если же вам нужно получить все пути, которые предоставляет WP REST API, то выполните запрос GET к конечной точке /wp-json.

Учитывая преимущество само документации, мы не будет рассматривать каждый индивидуальный ресурс в рамках этой серии руководства.

Что дальше?

В следующей части серии мы научимся выполнять CRUD операции, создание, обновление и удаление ресурсов.