Представляем WP REST API

Когда запускается следующая конечная точка, она возвращает конкретную сущность, т.е. сообщение, имеющее идентификатор 100:

Запрос POST создает новый объект, а запрос PUT заменяет этот объект новой версией.

Следующий запрос POST можно использовать для создания нового сообщения (отправка по телу запроса, которое мы рассмотрим в более поздней части серии) с использованием API-интерфейса WP REST:

И следующий запрос PUT обновит сообщение с идентификатором 100:

Запрос DELETE удаляет ресурс из системы. Этот тип запроса, наряду с запросом PUT является повторяемым, что означает, что вызов этих методов будет иметь такой же эффект в системе. Например, если вы вызываете PUT запрос несколько раз для ресурса (с одинаковыми аргументами), результат будет одинаковым. То же самое относится и к запросу DELETE . Многократное удаление ресурса будет иметь тот же эффект, т.е. ресурс будет удален (или будет возвращена ошибка в случае уже удаленного ресурса).

В дополнение к этим действиям CRUD служба RESTful предоставляет еще два глагола — OPTIONS и HEAD . Эти глаголы пригодятся, когда клиенту необходимо проверить, какие ресурсы доступны в системе и какие действия он поддерживает, что обеспечивает клиенту возможность самодокументирования для дальнейшего изучения системы и выполнения действий. Мы увидим эти два метода в действии позже в этом уроке.

Подробнее о маршрутах и ​​конечных точках

Обратите внимание, что в самом первом примере выше мы использовали следующую конечную точку :

Конечные точки — это функции, которые доступны через API, и они выполняют несколько действий, таких как получение сообщений (что мы делаем выше), создание нового пользователя или обновление мета публикации. В качестве альтернативы, мы можем сказать, что конечная точка запускает метод, который выполняет определенную задачу. Эти конечные точки зависят от глагола HTTP, связанного с ними. В приведенном выше примере мы используем глагол GET, чтобы получить все сообщения.

Маршрут для вышеуказанной конечной точки следующий:

Маршрут — это имя доступа к конечной точке. Маршрут может иметь несколько конечных точек на основе HTTP-глаголов. Таким образом, вышеприведенный маршрут имеет следующую конечную точку для создания нового сообщения:

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

Рассмотрим следующий маршрут:

Этот маршрут указывает на объект Post с идентификатором 100. Он имеет следующие три конечные точки:

1. GET wp/v2/posts/100 : который можно использовать для получения сообщения с идентификатором 100. Он вызывает метод get_item() .
2. PUT wp/v2/posts/100 : может использоваться для обновления записи с идентификатором 100. Он запускает метод update_item() .
3. DELETE wp/v2/posts/100 : удаляет запись с идентификатором 100. Он вызывает метод delete_item() .

Мы узнаем больше о внутренностях API REST WP, его структуре классов и внутренних методах в заключительной части этой серии.

Давайте теперь освежим наши знания о некоторых распространенных кодах ответов HTTP и их значении.

HTTP-коды ответа

Сервер отвечает на запрос, возвращая ответ, содержащий код состояния HTTP. Эти коды являются числами с предопределенными значениями, связанными с ними. Например, любой, кто использует Интернет, знаком с кодом состояния 404 , в котором указано, что ресурс, который искал пользователь, не был найден.

Ответ сервера также зависит от типа HTTP-глагола или метода, который мы используем в отправляемом запросе, как мы увидим далее.

Ниже приведены некоторые общие коды ответов HTTP вместе с их значениями, с которыми мы столкнемся при работе с WP REST API, и их значения:

• 200 - OK . Означает, что запрос был успешно выполнен и сервер вернул ответ. Обычно возвращается после успешного запроса GET .
• 201 - Created : обычно возвращается после успешного запроса POST . Подводит итог, что ресурс был создан.
• 400 - Bad Request : он возвращается с сервера, когда был отправлен запрос с некоторыми пропущенными или недействительными параметрами. Обычно возвращается в ответ на запросы POST или PUT .
• 401 - Unauthorized : означает, что пользователь не был авторизован для выполнения определенных действий. Например, пользователь попытался создать или удалить ресурс без предоставления учетных данных для аутентификации.
• 403 - Forbidden : означает, что сервер понял запрос, но отказался выполнить его из-за аутентификации. Это происходит, когда пользователь предоставляет учетные данные для аутентификации, но у него недостаточно прав для выполнения действия.
• 404 - Not Found : самый (не) известный из всех кодов состояния. Подводит итог, что ресурс, который искал пользователь, не был найден.
• 405 - Method not Allowed : означает, что ресурс HTTP, указанный в запросе, не поддерживается ресурсом. Примером может служить пользователь, пытающийся обновить ресурс только для чтения.
• 410 - Gone : означает, что ресурс был перемещен в другое место. Примером может быть попытка удалить уже удаленный ресурс, который был перемещен в корзину.
• 500 - Internal Server Error : возвращается, когда сервер обнаружил непредвиденное состояние и не завершил запрос.
• 501 - Not Implemented : означает, что сервер не поддерживает функциональные возможности для выполнения запроса. Обычно происходит, когда сервер получает метод запроса, который он не распознает.

Мы рассмотрим эти HTTP-глаголы и коды ответов более внимательно, когда начнем работать с API. Но перед этим давайте рассмотрим причины использования REST API с WordPress и преимущества, которые он предоставляет как разработчику, так и пользователю. В конце концов, мне нужно, чтобы вы были искренне заинтересованы следить за мной во время этой серии.

Зачем использовать JSON REST API для WordPress?

REST и JSON вместе предоставляют механизм для создания мощных приложений, использующих серверную часть WordPress. Наиболее яркими примерами являются мобильные приложения, которые требуют обмена данными между клиентом (устройством) и сервером. Принимая во внимание ограничения пропускной способности при использовании сотовых данных, JSON предоставляет легкую альтернативу решениям на основе XML.

Поскольку JSON является текстовым форматом для хранения данных, его можно беспрепятственно использовать с большинством языков программирования. Следовательно, JSON служит глобальным соединителем при обмене данными между различными платформами, которые одинаково читаются как машинами, так и людьми.

При использовании API, подобного обсуждаемому, содержание вашего сайта WordPress не ограничивается только им самим, но может быть доступно для других сайтов и клиентов. Поскольку API предоставляет некоторые части внутренней функциональности, удаленные клиенты могут взаимодействовать с вашим сайтом для обновления или создания нового контента. Это также позволяет извлечь некоторый контент с существующего сайта WordPress и показать его на каком-то другом сайте.

С появлением клиентских JavaScript-фреймворков, таких как Angular, Backbone или Ember, теперь стало возможным использовать один из них для создания насыщенного пользовательского интерфейса, при этом все еще используя серверную часть WordPress.

С учетом сказанного некоторые возможные варианты использования WP REST API:

• Мобильные приложения
• Пользовательские админ-панели для WordPress
• Одностраничные приложения (SPA)
• Интеграция с другими серверными платформами (такими как Ruby, .NET, Django и т. Д.)
• и многое другое…

Это действительно открывает новый мир возможностей, где единственным ограничением является воображение.

Краткая история JSON REST API в WordPress

До API REST на основе JSON API, используемый для удаленного взаимодействия с WordPress, был API-интерфейс XML-RPC, который все еще является частью ядра WordPress. Проблема с XML заключается в том, что он не такой легкий, как формат JSON, и его анализ неэффективен. Обход XML также является большой головной болью, в то время как обход объекта JSON так же прост, как обработка нативного объекта JavaScript.

Первым плагином REST API, который был представлен для WordPress, был JSON API , выпущенный в 2009 году. Он был создан в Музее современного искусства для их блога Inside / Out . Интерфейс этого блога был основан на Ruby on Rails, поэтому для извлечения сообщений и добавления комментариев в бэкэнд WordPress был разработан API. Этот плагин предоставляет интерфейсы для извлечения контента и отправки комментариев в бэкэнд WP. Хотя этот плагин не обновлялся более двух лет, он все еще присутствует в официальном репозитории и готов к использованию.

Помимо плагина JSON API, WordPress.com уже предоставляет JSON API через плагин JetPack .

WP REST API, как мы его знаем сегодня, является функциональным плагином, который был предложен Райаном МакКью в рамках GsoC (Google Summer of Code) 2013. Он еще не будет включен (полностью) в ядро ​​WordPress в будущем выпуске. Текущая версия плагина 2.0 находится в бета-состоянии и частично включена в ядро ​​WordPress версии 4.4. Это управляемый сообществом проект, возглавляемый Райаном МакКью и Рэйчел Бейкер . Официальная страница хранилища плагина находится на GitHub, а официальную документацию можно найти на его сайте .

Текущее состояние WP REST API

Как упоминалось выше, WP REST API в настоящее время находится в состоянии плагина и активно разрабатывается на GitHub. Он был частично включен в ядро ​​WordPress в версии 4.4, и Райан описал план в своем предложении о слиянии на WordPress.org.

Согласно предложению о слиянии, API-интерфейс WP REST будет включен в ядро ​​WP в два этапа, как описано ниже:

Слияние кода инфраструктуры

Согласно предложению, на начальном этапе только код уровня инфраструктуры будет объединен с ядром WP в выпуске 4.4. Этот инфраструктурный код является реальной базой API WP REST, поскольку он включает сериализацию / десериализацию JSON, компоновку, внедрение и, самое главное, уровень маршрутизации, который управляет API. Этот код не включает конечные точки и их классы контроллеров, но он обеспечивает основу для создания API внутри WordPress.

На момент написания статьи это состояние было завершено, и код инфраструктуры был объединен с ядром WordPress в версии 4.4.

Слияние конечных точек

Конечные точки для постов, страниц, пользователей, таксономий и т. Д. Будут включены в ядро ​​WP в выпуске 4.5, т.е. на один выпуск позже, чем слияние кода инфраструктуры. Конечные точки — это то, что делает API полезным для обычных клиентов. Они включают в себя большую сложность, включая сопоставление внешних данных в формате JSON с собственными типами данных WordPress, и наоборот. Они составляют две трети кода самого API с приблизительно 5500 строками.

Стратегия здесь заключается в том, чтобы укрепить доверие разработчиков к API, сначала предоставив код инфраструктуры в ядре. Это позволило бы разработчикам тем и плагинов создавать собственные API-интерфейсы для включения в их темы и плагины. Но поскольку конечные точки не будут включены на этом этапе, это изначально ограничит полезность API.

Разрыв между этими двумя выпусками даст основной группе коммиттеров WP достаточно времени для проверки конечных точек API.

Еще одним преимуществом, которое WP REST API принесет сообществу WordPress, является использование GitHub в версии, контролирующей проект. Поскольку все вклады в WordPress делаются через SVN и Trac, команда WP REST API вполне уверена в том, что улучшит процесс внесения вклада, сократив разрыв между Trac и GitHub.

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

Инструменты торговли

Чтобы начать тестирование с помощью API WP REST, нам понадобится HTTP-клиент, который будет использоваться для отправки запросов на сервер и просмотра ответа. Это действительно вопрос вашего выбора, но я буду использовать Postman для Google Chrome в этой серии. Другие альтернативы Почтальону:

• ОТДЫХ Легко для Firefox
• httpie для командной строки

Почтальон позволяет нам создавать быстрые HTTP-запросы разных методов, просматривать ответ от сервера и тестировать конфигурацию для аутентификации. Все эти функции будут чрезвычайно полезны при работе с WP REST API.

Следующее, что нам нужно иметь на нашем сервере, это WP-CLI. С WP-CLI мы можем удаленно управлять установкой WordPress из консоли без необходимости открывать окно браузера. Нам потребуется использовать WP-CLI в следующей части этой серии при настройке аутентификации OAuth 1.0a. Вы можете найти инструкции по установке на официальном сайте .

Помимо HTTP-клиента и WP-CLI, нам также нужны демонстрационные данные для нашей установки WordPress. Я предлагаю проверить Theme Unit Test (XML) или плагин Demo Data Creator, который позволяет создавать несколько постов, страниц и пользователей.

Установка плагина

На момент написания данного руководства текущая стабильная версия — 1.2.2, которую можно найти в официальном репозитории . В этой серии мы будем работать с версией 2.0, так как она была переписана с нуля и содержит много критических изменений. Вы можете получить бета-версию 2 со своей официальной страницы плагина или из репозитория GitHub .

Обратите внимание, что не рекомендуется устанавливать текущую бета-версию в вашей производственной среде. Я настроил локальную среду WordPress, и я рекомендую вам сделать это для целей разработки и тестирования.

Чтобы установить плагин из репозитория GitHub, откройте свой терминал и извлеките плагин после входа в каталог / wp-content / plugins / :

Плагин будет загружен в каталог / WP-API / .

Вы можете активировать его у администратора WordPress, чтобы продолжить тестирование с ним.

Чтобы плагин WP REST API работал, вам нужно включить красивые постоянные ссылки с WordPress. Здесь предполагается, что вы уже знаете, чтобы выполнить это основное действие. Если вы этого не сделаете, не беспокойтесь, так как WordPress.org поможет вам .

Оценка доступности API

После установки плагина мы можем оценить доступность API на нашем сервере. Мы не ограничены использованием API только на нашем сайте, фактически мы используем его на любом сайте, на котором он установлен и включен. Чтобы проверить API на других сайтах, мы можем отправить запрос HEAD на сайт следующим образом, используя ваш HTTP-клиент:

Это вернет что-то вроде следующего в заголовке ответа:

Заголовок Link указывает на корневой маршрут WP API, который в нашем случае следующий:

API также можно обнаружить через JavaScript в браузере (или jQuery), запросив DOM для соответствующего элемента <link> как показано ниже:

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

Что дальше?

В этой вводной части серии мы узнали много нового об архитектуре REST, API-интерфейсе WP REST и самом HTTP. Сначала мы рассмотрели основные понятия, например, что такое архитектура REST и как она может помочь разработчикам создавать лучшие приложения. Затем мы узнали о HTTP, его глаголах и типах ответов. Мы также рассмотрели краткую историю об API в WordPress и о том, чем API REST WP отличается от своих предшественников.

В заключительной части этого урока мы установили плагин от GitHub. После этого мы ознакомились с запросом HEAD который можно использовать для определения доступности API на нашем сервере, а также на других серверах.

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