WP REST API - знакомство с архитектурой REST

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

В этой серии материалов мы рассмотрим WP REST API и то, как он может быть использован для создания пользовательского опыта, который до этого либо был невозможен, либо довольно сложен в реализации. Сначала мы пройдёмся по основным понятиям REST и JSON, а затем исследуем доступные опции WP REST API.

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

Назад в школу с REST

REST (Representational StateTransfer) - это архитектурный стиль, который помогает создавать и организовывать распределённые системы. Он описывает веб как распределённое гипермедиа приложение, связанные ресурсы которого взаимодействуют друг с другом путём обмена состояниями представления ресурса.

Ресурсы - это главные строительные блоки REST архитектуры. По факту они являются главными строительными блоками самого веба, учитывая то, что веб иногда называют “ресурсо-ориентированным”.

Когда мы говорим о WordPress, этими ресурсами являются отдельные сущности, такие как посты, страницы, комментарии, кастомные типы постов и т.п. Для взаимодействия с ресурсами используются URI (Uniform Resource Identifier), идентификаторы ресурсов.

RESTful сервис относится к URI как к первичному пути для адресации ресурса. У ресурса может быть несколько представлений. Например, изображение может быть доступно в jpg, gif, или png форматах. Отношение между ресурсами и URI - один ко многим. URI может указывать только на один конкретный ресурс, но ресурс может иметь больше чем один URI.

Список ресурсов, которые на момент написания этого материала (WordPress 4.4) поддерживает WP REST API, указан ниже:

• Посты (Posts)
• Страницы (Pages)
• Медиа (Media)
• Кастомные типы постов (Custom Post Types)
• Мета поста (Post Meta)
• Ревизии (Revisions)
• Комментарии (Comments)
• Термины (Terms)
• Пользователи (Users)

Используя HTTP глаголы, мы можем выполнять различные действия над этими ресурсами.

HTTP глаголы

REST API по сути позволяет выполнять CRUD (Create Read Update Delete) операции (операции создания, чтения, обновления и удаления) над ресурсами, используя HTTP. Для этой цели REST использует ограниченный набор глаголов HTTP запросов, список которых мы видим ниже:

1. GET: используется для чтения или получения ресурса.
2. POST: используется для создания ресурса.
3. PUT: используется для обновления ресурса.
4. DELETE: используется для удаления ресурса.
5. HEAD: используется для проверки существования ресурса без возврата его представления.
6. OPTIONS: используется для получения всех глаголов, поддерживаемых ресурсом.

GET запрос получает информацию и является идемпотентным (тождественным). Например, клиент может вызвать его множество раз, но это не повлияет на состояние ресурса, что подразумевает получение идентичных данных.

Для получения всех постов с помощью WP REST API, мы используем следующую конечную точку:

GET wp/v2/posts

Вышеуказанная точка возвратит коллекцию всех сущностей постов.

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

GET wp/v2/posts/100

POST запрос создаёт новую сущность, а PUT запрос заменяет эту сущность новой версией.

Следующий POST запрос может быть использован для создания нового поста (отправляется вместе с телом запроса):

POST wp/v2/posts

А этот PUT запрос обновит пост с id равным 100:

PUT wp/v2/posts/100

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

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

Маршрутизация и конечные точки

В предыдущих примерах мы использовали следующую конечную точку:

GET wp/v2/posts

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

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

wp/v2/posts

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

POST wp/v2/posts

Эта конечная точка, вызванная с соответствующими параметрами, создаст новую сущность типа пост. Давайте возьмём такой маршрут:

wp/v2/posts/100

Этот маршрут до сущности пост с id равным 100. Он имеет следующие три конечные точки:

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

Мы рассмотрим структуру класса WP REST API и его внутренние методы в финальной части этой серии материалов.

А сейчас давайте освежим наши знания о некоторых общих кодах ответов 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: означает, что сервер не поддерживает функционал для завершения запроса. Обычно случается, когда сервер получает метод запроса, который он не может распознать.

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