Основы WordPress REST API
Цель проекта, доступного сейчас в виде плагина REST API, состоит в том, чтобы включить предсказуемые ресурсоориентированные URL-адреса, стандартизированные возвращаемые структуры, и чтобы использовать коды ответа HTTP для вывода API-ошибок.
В данной статье я рассмотрю основы REST API, покажу вам, как вы можете использовать API прямо сейчас, чтобы сделать свой сайт или приложение гораздо лучше.
Основы
После того как вы скачали и активировали плагин, API готов к работе. Базовым путем API будет /wp-json/. Это означает, что для получения всех ваших записей из стороннего приложения вы можете сделать запрос к http://yoursite.com/wp-json/something.
В большинстве случае «something» в URL будет начинаться с «/wp/v2»; это означает, что вы используете версию 2 данного API.
Самый простой способ протестировать новый API – это зайти на сайт, убедиться в том, что плагин активирован, после чего посетить какой-либо маршрут. К примеру, вы можете проверить http://yoursite.com/wp-json/wp/v2/posts.
Если вы видите ответ, однако он представляет собой просто кучу текста, я советую использовать JSON Formatter для Chrome или JSONView для Firefox.
HTTP методы
REST API использует HTTP-методы, определяющие тип действий, которые клиент может совершить. Могут использоваться методы HEAD, GET, POST, PUT и DELETE, являющиеся стандартными в сети.
HEAD используется для получения информации о HTTP-заголовке, GET получает информацию о ресурсе, POST создает ресурс, PUT обновляет ресурс и DELETE удаляет ресурс. Ресурсы – это отдельные объекты в WordPress: записи, комментарии, пользователи и т.д.
Маршруты и конечные точки
Конечные точки – это специальные функции, которые могут быть активированы путем отправки соответствующего HTTP-метода к соответствующему URL-адресу. Маршрут – это сам URL, конечная точка – это комбинация пути и типа используемого действия.
/wp/v2/posts/342 – маршрут, состоящий из трех конечных точек. Использование GET получает ресурс, использование PUT (вместе с параметрами) обновляет ресурс, а DELETE удаляет его.
Использование API
Начиная с этого момента вы можете делать практически все, что вы могли бы выполнить в обычной WordPress. Вы можете создавать записи, обновлять пользователей, модерировать комментарии – все это вы можете делать из любого приложения. Вам нужно лишь знать маршруты, конечные точки, схему и параметры. Главная страница с документацией по API содержит в себе всю информацию по этим пунктам.
Если вам требуется список всех доступных маршрутов, вы можете просто отправить GET-запрос к /wp/v2/. Вы можете вывести на экран все маршруты и конечные точки, характерные именно для вашего сайта – ведь вы всегда можете создавать свои собственные маршруты.
Аутентификация
Первое, на что нужно обратить свое внимание – это аутентификация. Да, это довольно сложный процесс. Как только вы разберетесь в нем, все остальное вам покажется простым. В данный момент имеется три доступных типа аутентификации:
- Cookie-аутентификация – для плагинов и тем, работающих на одном и том же сайте
- OAuth – для внешних клиентов
- Базовая аутентификация – только для целей тестирования
Я рекомендую вам использовать базовую аутентификацию только с целью обучения, поэтому, пожалуйста, не используйте ее на рабочих сайтах – это небезопасно.
Для начала вам нужно будет установить плагин Basic Auth. Плагин доступен только на Github, вы можете установить его, скачав и загрузив zip-архив.
Чтобы показать, как обратиться к API отдельной сборки WordPress, я напишу некоторый PHP-код на моей локальной машине, который получит доступ к метаданным записей на моем реальном сайте.
Для получения публично доступных данных вы можете использовать функцию wp_remote_get():
$response = wp_remote_get( 'http://danielpataki.com/wp-json/wp/v2/posts');
В переменной $response будет находиться набор данных, включая список записей. Если вы попробуете применить тот же самый метод к закрытому ресурсу, вы получите ошибку: «Sorry, you cannot view the meta for this post» («Вы не можете просмотреть метаданные для этой записи»). Именно здесь и выходит на передний план аутентификация.
Используя базовую аутентификацию, мы можем отправить наше имя пользователя и пароль вместе с каждым запросом, который наделит нас должными правами доступа.
$response = wp_remote_get( 'http://username:password@danielpataki.com/wp-json/wp/v2/posts/445/meta');
Этот вызов будет успешным, я смогу просмотреть все метаданные записи, связанные с записью 445. Недостатки этого метода очевидны.
Вам нужно отправлять свое имя пользователя и пароль с каждым запросом и – что еще хуже – в виде обычного текста! Поэтому повторяю: такой подход хорош только в целях тестирования и изучения работы API, но он не подойдет для использования в продакшне.
Отправка данных
Получить ресурсы очень просто. Вы применяете метод GET к соответствующей конечной точке и получаете обратно JSON, который вы можете обработать прямо в JS либо конвертировать его в массив с помощью json_decode() в PHP. Что по поводу более сложных процедур, когда нам нужно передать данные, зачастую с параметрами? В примере ниже мы создаем запись через REST API.
$args['body'] = array(
'title' => 'API TEST',
'status' => 'draft',
'content' => 'content'
);
$response = wp_remote_post( 'http://username:password@danielpataki.com/wp-json/wp/v2/posts/', $args );
Чтобы понять, что именно нужно добавить к телу запроса, нужно взглянуть в схему. Она содержит названия параметров, типы данных, описание и контекст.
Ответ содержит некоторую информацию о нашей новой записи, включая ID, который может пригодиться в том случае, если мы хотим управлять метаданными после добавления записи.
Заключение
Я надеюсь, что примеры показали вам, как работать с JSON API. В скором времени API появится в ядре, что вынесет существующие приложения на новый уровень и позволит разработчикам создавать мобильные клиенты для комплексных сайтов, работающих на WordPress.
Еще одно базовое руководство по работе с Wordpress REST API представлено по ссылке.
Источник: kinsta.com
