Базовое руководство по REST API
*Расположенный ниже текст частью является моим вольным переводом документации разработчиков WordPress, расположенного по адресу «https://developer.wordpress.org/rest-api/». Весь перевод идет в контексте применимости к 1С. Надеюсь он вам поможет в понимании не только REST API Wordpress’а, но других CMS, плагинов и так далее. В основном использовался Yandex переводчик.
REST API WordPress предоставляет конечные точки API для типов данных WordPress, которые позволяют разработчикам удаленно взаимодействовать с сайтами, отправляя и получая объекты JSON (JavaScript Object Notation). JSON-это открытый стандартный формат данных, который является легким и удобочитаемым для человека и выглядит как объекты в JavaScript; отсюда и название. Когда вы отправляете контент или делаете запрос к API, ответ будет возвращен в JSON. Это позволяет нам, как разработчикам, создавать, читать и обновлять контент WordPress из клиентского JavaScript или из внешних приложений, даже тех, которые написаны на языках за отличными от PHP.
Зачем использовать WordPress REST API
REST API WordPress делает работу с контентом проще, чем когда-либо, чтобы использовать WordPress в новых и интересных способах разработки. Вам даже не придется писать приложения на PHP: любой язык программирования, который может делать HTTP-запросы и интерпретировать JSON, может взаимодействовать с WordPress через REST API.
WordPress REST API также может служить надежной заменой API admin-ajax в ядре. Используя REST API, вы можете более легко структурировать способ, которым вы хотите получать данные в WordPress и из него. Вызовы AJAX можно значительно упростить с помощью REST API, что позволит вам тратить меньше времени на доступ к нужным данным и больше времени на создание лучшего пользовательского интерфейса.
Наше воображение - это единственный предел того, что можно сделать с помощью API REST WordPress. Суть в том, что, если вам нужен структурированный, расширяемый и простой способ получения данных в WordPress и из него через HTTP, вы, вероятно, захотите использовать REST API. При всей своей простоте REST API может показаться довольно сложным на первый взгляд, и мы попытаемся разбить его на более мелкие компоненты, чтобы мы могли легко собрать весь пазл воедино.
Ключевые принципы (Key Concepts)
Чтобы начать работу с использованием WordPress REST API, мы разберем некоторые ключевые понятия и термины, связанные с API:
• Routes/Endpoints / Маршруты / Конечные точки
• Requests / Запросы
• Responses / Ответы
• Schema / Схема
• Controller Classes / Классы контроллеров
Каждая из этих концепций играет решающую роль в использовании и понимании REST API WordPress. Давайте вкратце разберем их, чтобы позже мы могли изучить каждый из них более глубоко.
Routes & Endpoints
Маршрут (route), в контексте WordPress REST API, является URI, который может быть сопоставлен с различными методами HTTP. Сопоставление отдельного метода HTTP с маршрутом называется "конечной точкой" (endpoint). Чтобы быть точным: если мы сделаем запрос GET http://oursite.com/wp-json/, мы получим ответ JSON, показывающий нам, какие маршруты доступны, и в каждом маршруте, какие конечные точки доступны. /wp-json/ - это сам маршрут, и когда делается запрос GET, он соответствует конечной точке, которая отображает то, что известно, как индекс для WordPress REST API.
REST API предоставляет нам способ сопоставления URI с различными ресурсами в нашей WordPress. По умолчанию, если у вас есть и включены постоянные ссылки, WordPress REST API “живет” в /wp-json/. На нашем сайте WordPress https://ourawesomesite.com, мы можем получить доступ к индексу REST API, сделав запрос GET к https://ourawesomesite.com/wp-json/. Индекс предоставляет информацию о том, какие маршруты доступны для этой конкретной установки WordPress, а также о том, какие методы HTTP поддерживаются и какие конечные точки зарегистрированы.
В двух словах:
Маршрут (Route) — это «имя», которое отсылает работу API WordPress к определенным эндпоинтам. Если совсем просто, маршрут - это URL к которому можно обратиться разными HTTP методами. Маршрут может иметь несколько эндпоинтов.
Конечная точка (Endpoint) — это само обращение к маршруту отдельным HTTP методом. Эндпоинты выполняют конкретную задачу, принимают параметры и возвращают данные Клиенту.
Типовые (штатные) конечные точки WordPress:
GET — получает список (или отдельную позицию) и возвращает данные поста Клиенту.
PUT|PATCH|POST — обновляет данные и возвращает их Клиенту.
DELETE — удаляет что-либо и возвращает только что удаленные данные Клиенту.
Например,
• GET /wp/v2/posts
• POST /wp/v2/posts
• POST /wp/v2/posts/<id>
• DELETE /wp/v2/posts/<id>
Requests
Одним из основных классов в инфраструктуре REST API WordPress является класс WP_REST_Request. Этот класс используется для хранения и извлечения информации для текущего запроса; запросы могут быть отправлены удалённо через HTTP. WP_REST_Request объекты автоматически создаются для вас, когда вы делаете HTTP-запрос к зарегистрированному маршруту. Данные, указанные в запросе, определят, какой ответ вы получите обратно из API. Есть много изящных вещей, которые вы можете сделать с помощью класса запроса.
Здесь мы запросили всё, что касается только WordPress, маршруты, конечные точки, аргументы для запросов и т.д.
Responses
Ответы - это данные, которые вы получаете от API. Класс WP_REST_Response предоставляет способ взаимодействия с данными ответа, возвращаемыми конечными точками. Ответы могут возвращать нужные данные, а также могут использоваться для возврата ошибок.
В качестве примера введите в строке браузера маршрут «http://oursite.com/wp-json/» и вы получите ответ как на рисунке ниже (при условии конечно, что WordPress REST API не отключен каким-нибудь плагином или иным способом).
Здесь запросили вообще всё, что предоставляет WordPress, ответ получили в «сыром», необработанном виде. В удобочитаемом виде смотрите рисунки выше.
Schema
Каждая конечная точка требует и предоставляет несколько разных структур данных, и эти структуры определены в схеме API. Схема структурирует данные API и предоставляет полный список всех свойств, которые API может возвращать, и входных параметров, которые он может принимать. Схема также обеспечивает преимущества безопасности для API, поскольку она позволяет нам проверять запросы, выполняемые к API.
Controller Classes
Как вы можете видеть, WordPress REST API имеет много движущихся частей, которые должны работать все вместе. Классы контроллеров объединяют все эти элементы в одном месте. С помощью класса контроллера вы можете управлять регистрацией маршрутов и конечных точек, обрабатывать запросы, использовать схему и генерировать ответы API. *Полагаю, что данный пункт необходим для разработчиков на PHP и по крайней мере в ближайшее время на не понадобится. Во всяком случае, сколько работаю с Rest API WordPress, до сих пор мне это было не нужно.
На этом базовая вводная окончена, надеюсь у вас не возникнут сложности с пониманием описанного.
Категории постов/страниц WordPress
А теперь настала пора перейти к более интересному, чем чтение. В этой части рассмотрим примеры работы с категориями постов/страниц WordPress, как самым простым и легким образцом для экспериментов (по моему скромному мнению).
*Небольшая ремарка с пояснениями: в самом начале работы с Rest API WordPress столкнулся с тем, что 1С и схемы свойств данных Rest API WordPress имеют одинаковые написания на латинице. Например «title», «description», «name» и т.д., в следствии чего не мог задать реквизиты в 1С с подобными именами. В результате чего ввел две структуры «переводчики»:
- ВП_СтруктураСоответствийСРусскогоНаАнг – перевод с имен реквизитов с «русского» на английский
(например: ВП_СтруктураСоответствийСРусскогоНаАнг.Вставить(Врег("Наименование"),"name"))
- ВП_СтруктураСоответствийСАнгНаРусского – обратный переводчик.
Это позволяет быстро сопоставлять реквизиты 1С и Rest API WordPress. И заполнять данные через штатную функцию «ЗаполнитьЗначенияСвойств(<Приемник>, <Источник>)»
Схема категорий постов/страниц
Посмотреть полностью можно тут: https://developer.wordpress.org/rest-api/reference/categories/
Конечные точки. Сопоставление с 1С.
Ниже приведенный код выполняет действие на сайте согласно конечной точке WordPress.
Функция рс_ПослатьГотовыйЗапросНаСайт(ТипЗапроса, СтрокаПодключенияСервера, Запрос) Экспорт
СоединениеССервером = онОбщегоНазначения_ПолучитьСоединениеHTTPS(СтрокаПодключенияСервера, , , , , ,);
Если ВРег(ТипЗапроса) = "POST" Тогда
Результат = СоединениеССервером.ОтправитьДляОбработки(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "GET" Тогда
Результат = СоединениеССервером.Получить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "PUT" Тогда
////Результат = СоединениеССервером.Записать(Запрос); /////Эта функция не работает
Результат = СоединениеССервером.Изменить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "PATCH" Тогда
Результат = СоединениеССервером.Изменить(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "HEAD" Тогда
Результат = СоединениеССервером.ПолучитьЗаголовки(Запрос);
ИначеЕсли ВРег(ТипЗапроса) = "DELETE" Тогда
Результат = СоединениеССервером.Удалить(Запрос);
КонецЕсли;
Возврат Результат;
КонецФункции //
Получение всех категорий списком.
Запрос для сайта будет выглядеть так: «GET /wp/v2/categories»
Конечная точка «GET». Маршрут «/wp/v2/categories». На данном этапе какие-либо дополнительные аргументы для вызова списка категорий не нужны, WordPress отработает запрос своими аргументами по умолчанию.
В программе категории/рубрики WordPress заведены как справочник «Категории/рубрики постов/страниц сайта WordPress».
На рисунке видим, что можно выполнить все типовые запросы к сайту, по коду, приведенному выше, плюс один собственный запрос, который после выполнения запроса на получения списка категорий, автоматически создает все категории в справочнике, по данным полученным от сайта.
Выполним все команды, для этого надо выбрать тип из списка, а потом нажать соответствующую кнопку.
Запросим данные с сайта и создадим все категории в справочнике.
А вот так они выглядят на сайте
Возьмем для примера категорию «Тестовая категория1».
Так выглядит на сайте до изменения
И изменим наименование, описание и родителя и запишем. Запрос для сайта будет выглядеть так: «POST /wp/v2/categories/<id>»
Изменим на сайте выбрав «Обновить (текущий)»
Так стало выглядеть на сайте
Чтобы создать категорию/рубрику на сайте создайте элемент справочника, запишите и закройте его, после чего выбрав в списке пошлите запрос на сайт выбрав «Создать (один)».
Запрос для сайта будет выглядеть так: «POST /wp/v2/categories»
Так выглядит на сайте
Ну и соответственно удалим тестовые категории. Элемент справочника помечается на удаление и у него удаляется id.
Запрос для сайта будет выглядеть так: «DELETE /wp/v2/categories/<id>»
Соответственно с сайта они исчезли
Ну и запрос данных по конкретной категории выглядит так «GET /wp/v2/categories/<id>». Здесь пример приводить не стал, попробуйте сами.
И напоследок:
В обновленную конфигурацию добавлены демо-запросы к сайту.
Обновлена демо-обработка для тестов с новыми запросами,
добавлена возможность посылать запросы «GET» к сайту по своим маршрутам.
На этом всё, вторая часть окончена.
Желаю приятных экспериментов на ниве обмена из 1С с сайтом WordPress.
Продолжение следует.
В следующей части будем публиковать/изменять/удалять сами посты/страницы.
Обработка тестировалась:
Тестировалось на моем сайте: перейти.
Версия WordPress: 5.2
MySQL Версия : 5.7.23-24
PHP Версия : 7.3.6
Платформа: 1С:Предприятие 8.3 (8.3.13.1644)
P.S. Если вам интересна описанная в публикации тема, вы готовы посвятить этому некоторое своё свободное время, есть желание, милости прошу присоединиться к моему проекту, пишите, не стесняйтесь.
