Как отправить запрос к api сайта и получить ответ json

JSON От теории к практике, что такое JSON и как с ним работать

Подумала я подумала и решила, поговорим о JSON! Но не на языки великой и всемогущей «Википедии» где статьи пишутся по моему в большинстве своём для сверх разума, а не для людей. Так же не буду парить тебе мозг, на кучу абзацев тем, что JSON это текстовый формат данных, который явился из JavaScript и прочею скучную хернь. Ну, все это нахер…

Мы пойдём другим путём более интересным и информативным, что бы было ясно, зачем и для чего может пригодится JSON и как с ним работать. Сначала не много болтовни, а после пару практических примеров. Поработаем с какой-нибудь API системой и на практике убедится, что JSON это очень круто, просто и удобно!

Где и для чего используется JSON

Вы можете использовать JSON везде, где есть необходимость для передачи или получения какой либо информации, между приложениями. Или использовать JSON как бы локально, просто хранить там какие-то настройки своего приложения. Как я это уже делала в соседней статье.

Например: Сервер — Клиент.
Имеем сервер, на сервере стоит база данных которая таит в себе некую информацию. Эту информацию нам нужно получить, например из python приложения, которое вы кодите на своём ПК. Возникает вопрос, как? Вот тут-то JSON себя и проявляет во всей красе.

Ложем на сервер, скажем PHP скрипт, который мониторит входящие GET запросы. Из приложухи python отправляем запрос на сервер, PHP ловит запрос… ломится в базу данных и вытаскивает от туда информацию в виде массива. Далее полученный массив преобразуется в JSON и как обычный текст отправляется в приложения python. А там уже можно декодировать JSON и продолжить работу с инфой полученной из Базы Данных! Удобно? Круто? Да это б*ять п*здец как ахуе*но!

Например: В пределах одного приложения.
Кодите вы что-то там, такое не большое и простое. Есть необходимость где-то, что-то хранить, некую статистическую информацию, которая никогда не меняется и при этом часто используется в приложении. Использовать БД не вариант, зато JSON подойдёт в самый раз. Как такой пример работает в действии, читайте в соседней статье, ссылку кинул выше…

Синтаксис и структура JSON

Прежде чем приступить к разбору JSON надо понять и разобраться в том, как собственно все это дело создаётся и записывается в файл. Синтаксис достаточно простой и не должен вызвать каких-то сложностей. Достаточно запомнить следующие моменты и посмотреть на примеры.

Общие принципы:

Массив всегда заключается в квадратные скобки [ … ]
Объект нужно заключать в фигурные скобки
Свойства и значения в двойных кавычках разделённые ( : ) «Значение» : «Свойства»

Свойства может быть:

Логическим (true или false).
Числом, записывается без двойных кавычек.
Строкой, записывается в двойные кавычки.
Массивом или объектом.

Когда основные моменты структуры JSON известны, рассмотрим примеры JSON файлов и начнём с самого примитивного и простого примера.

Если декодировать этот пример из приложения, например из PHP используя функцию json_decode() то вывод будет следующим.

[cc lang=»php»]
stdClass Object
(
[Машка] => 28 год
[Дашка] => 35 лет
[Анжелка] => 30 лет
)
[/cc]

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

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

Давай сделаем все не много интереснее и усложним пример. Разделим логически записи для каждой особы, что бы добавить для каждой девушки информацию о ней.

Обратите внимание, что за последним элементом не ставится запитая, как после свойства так и объекта. Посмотрим, какой теперь будет ответ.

[cc lang=»php»]
stdClass Object
(
[Машка] => stdClass Object
(
[Возрост] => 33
[1 час] => 150$
)

[Дашка] => stdClass Object
(
[Возрост] => 28
[1 час] => 200$
)

[Анжелка] => stdClass Object
(
[Возрост] => 28
[1 час] => 100$
)

Теперь все куда интереснее. Можно из программы получить нужный объект, например «[Дашка]» и посмотреть что там за час))) Но что если и этого мало. Нужно больше информации и по каждому объекту. Можно присобачить массив. Далее буду использовать примеры JSON в более коротком варианте, либо листинги длинные…

Ну и стразу можно посмотреть в каком виде прилетит ответ. Кстати, в этом примере [] можно убрать, они тут в принципе и нахер не нужны, но для примера сойдёт.

[cc lang=»php»]
stdClass Object
(
[Машка] => stdClass Object
(
[Возрост] => 33
[1 час] => 150$
[Доп инфа] => Array
(
[0] => stdClass Object
(
[Рост] => 169
[Статус] => 1
)

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

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

JSON в практических примерах

Первое что в голову приходит, это взять соц.сеть, например API VK и поработать с ним, но нет. Не охота тратить время на создание приложения, подтверждать все по СМС и прочие, и вообще ВК дно…

Не много подумал, если же coinmarketcap.com/api/ с публичным API без всяких ключей и секретов. Круто, будем писать крипто приложение, можно какойнить виджет на сайт замутить))) Напишем прогу которая будет сообщать, какие монеты находятся в ТОП 3, какие цены, и всю херню…

Отправляем запрос на сервер

Ломимся на coinmarketcap.com и смотрим что там есть. Что бы получить ТОП 3 манеты можно отправить GET запрос по адресу http://api.coinmarketcap.com/v2/ticker/?limit=10 где параметру limit передать нужно количество монет «Значение», нас интересует 3. Пишем код.

[cc lang=»php»]
$ticker = file_get_contents(‘http://api.coinmarketcap.com/v2/ticker/?limit=3’);
$ticker = json_decode($ticker);

И сразу смотрим ответ, что там пришло.

Видим уже нечто знакомое, это сервер вернул ответ в JSON формате, в котором содержится целая куча всякой разной информации по каждой монете. Теперь осталось разобрать все это дело и забрать только то, что нам нужно. Пишем код дальше.

[cc lang=»php»]
$ticker = file_get_contents(‘http://api.coinmarketcap.com/v2/ticker/?limit=3’);
$ticker = json_decode($ticker);

Для примера я взяла только некоторую часть информации, а остальное брать не буду, сами разбирайтесь))) Результат работы этой крутой и полезной программы представлен на этом скнине.

Как вы понимаете я использую консоль, по скольку все это дело на PHP думаю понятно, как просто вывести все это дело на сайте.

На этом работа с JSON на сегодня окончена, мы посмотрели пару примеров, и написали программу, которая прекрасно демонстрирует всю прелесть и удобство JSON.

Принципы построения REST JSON API

Эта памятка писалась для внутренних нужд (открыть глаза менее опытным в вебе коллегам). Но, т.к. я насмотрелся велосипедов от довольно уважаемых, казалось бы, контор, — выкладываю на хабр. Мне кажется, многим будет полезно.

Зачем

Надеюсь, читающий уже понимает, зачем ему вообще нужен именно REST api, а не какой-нибудь монстр типа SOAP. Вопрос в том, зачем соблюдать какие-то стандарты и практики, если браузеры вроде бы позволяют делать что хочешь.

Стандарт HTTP это стандарт. Его несоблюдение вредно для кармы и ведёт к постоянным проблемам с безопасностью, кэшированием и прочими «закидонами» браузеров, которые совсем не закидоны, а просто следование стандарту.
Велосипеды со всякими невозможно нормально тестировать и отлаживать
Поддержка большим количеством готовых клиентских библиотек на все случаи жизни. Те, кто будет вашим api пользоваться, скажут большое человеческое спасибо.
Поддержка автоматизированного интеграционного тестирования. Когда сервер на любые запросы отдаёт 200 ОК — ну, это такое себе развлечение.

Структура запросов и ответов

Любой http-запрос начинается со строки

где METHOD — это метод доступа (GET, PUT и т.д.), а URI — адрес запрашиваемого ресурса.

В начале запроса идут заголовки — просто текстовые строки вида key: value
Затем передаётся пустая строка, означающая конец секции заголовков, и затем — тело запроса, если оно есть.

В ответе сначала передаётся строка с версией http, кодом и строковым статусом ответа (например HTTP/1.1 200 OK ), далее текстовые заголовки ответа, потом пустая строка, потом тело ответа.

Тут вроде всё просто.

Кодирование запросов и ответов

Кодировка для всех и запросов, и ответов — UTF-8 и только UTF-8, т.к. некоторые, кхм, «браузеры» имеют привычку игнорировать содержимое заголовка charset.

Использование кодов символов и html-сущностей не допускается, т.е. режим JSON_UNESCAPED_UNICODE обязателен. Не все клиенты знают всю таблицу html сущностей (типа каких-нибудь ù ), да и при чём тут html. Не все клиенты готовы/хотят заниматься перекодированием \uXXXX; и &#XX;. Плюс возможны «весёлые» ситуации с избыточным экранированием или пропаданием слэшей и амперсандов.

Все данные, кроме URI и двоичных файлов, передаются в формате JSON. Обратите внимание, что далеко не всякий валидный javascript код является валидным JSON.
В частности, для строк используются только двойные кавычки. Одинарные кавычки в json-данных, хотя и допустимы в «обычном» javascript, могут вызвать непредсказуемые плохо отлавливаемые баги.

В запросах обязательно указывается заголовок

Вызовы к API отличаются от прочих вызовов (например, обычной загрузки html страницы по данному URI) именно по наличию application/json в Accept.

Сама строка Accept формируется браузером/клиентом и может немного отличаться от браузера к браузеру, например, наличием и других форматов типа text/javascript , поэтому нужно проверять не равенство, а именно вхождение «application/json».

В ответах 2хх с непустым телом обязательно наличие заголовка ответа

При наличии тела запроса также обязателен заголовок запроса

либо, при загрузке файлов,

и далее, в первой части

после чего для каждого файла

Если вы используете защиту от CSRF (а лучше бы вам её использовать), то удобнее передавать CSRF-токен в отдельном заголовке (типа X-CSRF-Token) для всех запросов, а не внедрять вручную в каждый запрос. Хранить CSRF токен в куках плохо по той причине, что куки можно украсть, в чём собственно и состоит суть CSRF атаки.

Структура URI

Нагородить можно всякое, но лучшая практика — чтобы все URI имели вид

ну, или если у вас api лежит в какой-то папке,

entity — название сущности, например, класса или таблицы/представления в БД. Примеры: users , dictionary
idopt. — первичный ключ объекта. Если первичный ключ составной, то части указываются через слэш. Примеры: /users/10 , /dictionary/ru/apptitle
paramsopt. — дополнительные параметры выборки для списочных запросов (фильтрация, сортировка, паджинация и пр.). Форматируются по правилам HTTP GET параметров (функции encodeURIComponent и пр.)

Для разбора части URI до знака вопроса можно использовать регулярку

Ведущий слэш обязателен, т.к. неизвестно, с какого URL будет осуществлён запрос.

Методы HTTP

GET /:entity/:id — getById

В случае успеха сервер возвращает 200 OK с полями объекта в формате JSON в теле ответа (без дополнительного оборачивания в какой-либо объект)

В случае, если объект с такими id не существует, сервер возвращает 404 Not Found

В ответе обязательно должны быть заголовки, касающиеся политики кэширования, т.к. браузеры активно кешируют GET и HEAD запросы. При остутствии какой-либо политики управления кэшем должно быть:

GET /:entity[?param1=. &param2=. ] — списочный get

Простой случай: в случае успеха сервер возвращает 200 OK с массивом объектов в формате JSON в теле ответа (т.е. ответ начинается с [ и заканчивается ] ).

Если массив получился пустой, всё равно вовзращается 200 OK с пустым масивом [] в теле ответа.

Более сложный вариант: возвращается объект, в одном из полей которого — искомый массив. В остальных полях — данные о пагинации, фильтры, счётчики и пр. Только держите это консистентным по всем api.

HEAD /:entity[/:id] — запрос заголовков

Полный аналог GET с таким же URI, но не возвращает тело ответа, а только HTTP-заголовки.

Реализация поддержки HEAD запросов веб-сервером обязательна.

Активно используется браузерами в качестве автоматических pre-flight запросов перед выполнением потенциально опасных, по их мнению, операций. Например, браузер Chrome активно кидается head-запросами для получения политик CORS при кросс-доменных операциях (виджеты и пр). При этом ошибка обработки такого head-запроса приведёт к тому, что основной запрос вообще не будет выполнен браузером.

Может использоваться для проверки существования объекта без его передачи (например, для больших объектов типа мультимедиа-файлов).

POST /:entity — создаёт новый объект типа :entity

В теле запроса должны быть перечислены поля объекта в формате JSON без дополнительного заворачивания, т.е.

В случае успеха сервер должен возвращать 201 Created с пустым телом, но с дополнительным заголовком

указывающим на месторасположение созданного объекта.

Возвращать тело ответа чаще всего не требуется, так как у клиента есть все необходимые данные, а id созданного объекта он может получить из Location.

Также метод POST используется для удалённого вызова процедур (RPC), в этом случае ответ будет иметь статус 200 OK и результаты в теле. Вообще смешивать REST и RPC в одном api — идея сомнительная, но всякое бывает.

Единственный неидемпотентный некешируемый метод, т.е. повтор двух одинаковых POST запросов создаст два одинаковых объекта.

PUT /:entity/:id — изменяет объект целиком

В запросе должны содержаться все поля изменяемого объекта в формате JSON.

В случае успеха должен возвращать 204 No Data с пустым телом, т.к. у клиента есть все необходимые данные.

Идемпотентный запрос, т.е. повторный PUT с таким же телом не приводит к каким-либо изменениям в БД.

PATCH /:entity/:id — изменяет отдельные поля объекта

В запросе должны быть перечислены только поля, подлежащие изменению.

В случае успеха возвращает 200 OK с телом, аналогичным запросу getById, со всеми полями изменённого объекта.

Используется с осторожностью, т.к. два параллельных PATCH от двух разных клиентов могут привести объект в невалидное состояние.

DELETE /:entity/:id — удаляет объект, если он существует.

В случае успеха возвращает 204 No Data с пустым телом, т.к. возвращать уже нечего.

Идемпотентный запрос, т.е. повторный DELETE с таким же адресом не приводит к ошибке 404.

OPTIONS /:entity[/:id]

Получает список методов, доступных по данному URI.

Сервер должен ответить 200 OK с дополнительным заголовком

Некешиуремый необязательный метод.

Обработка ошибок

Возвращаемые ошибки передаются с сервера на клиент как ответы со статусами 4хх (ошибка клиента) или 5хх (ошибка сервера). При этом описание ошибки, если оно есть, приводится в теле ответа в формате text/plain (без всякого JSON). Соответственно, передаётся заголовок ответа

Использовать html для оформления сообщений об ошибках в api — так себе идея, будут проблемы журналированием и т.д. Предполагается, что клиент способен сам красиво оформить сообщение об ошибке для пользователя.

При выборе конкретных кодов ошибок не следует слишком увлекаться и пытаться применить существующие коды только потому, что название кажется подходящим. У многих кодов есть дополнительные требования к наличию определённых заголовков и специальная обработка браузерами. Например, код 401 запускает HTTP-аутентификацию, которая будет странно смотреться в каком-нибудь приложении на react или electron.

UPD по мотивам комментариев. Клиенты у вас будут разные: не только веб и мобильные приложения, но и такие штуки, как запускалка интеграционных тестов (CI), балансировщик нагрузки или система мониторинга у админов. Использование или неиспользование того или иного статуса ошибки определяется тем, будет ли он полезен хоть какому-то клиенту (т.е. этот клиент сможет предпринять какие-то действия конкретно по этому коду) и, наоборот, не будет ли проблем у какого-то из клиентов из-за неиспользования вами этого кода. Придумать реальный use-case, когда реакция клиента будет различаться в зависимости от 404 или 410, довольно сложно. При этом отличий 404 от 200 или 500 — вагон и телега.

400 Bad Request

Универсальный код ошибки, если серверу непонятен запрос от клиента.

403 Forbidden

Возвращается, если операция запрещена для текущего пользователя. Если у оператора есть учётка с более высокими правами, он должен перелогиниться самостоятельно. См. также 419

404 Not Found

Возвращается, если в запросе был указан неизвестный entity или id несуществующего объекта.

Списочные методы get не должны возвращать этот код при верном entity (см. выше).

Если запрос вообще не удалось разобрать, следует возвращать 418.

415 Unsupported Media Type

Возвращается при загрузке файлов на сервер, если фактический формат переданного файла не поддерживается. Также может возвращаться, если не удалось распарсить JSON запроса, или сам запрос пришёл не в формате JSON.

418 I’m a Teapot

Возвращается для неизвестных серверу запросов, которые не удалось даже разобрать. Обычно это указывает на ошибку в клиенте, типа ошибки при формировании URI, либо что версии протокола клиента и сервера не совпадают.

Этот ответ удобно использовать, чтобы отличать запросы на неизвестные URI (т.е. явные баги клиента) от ответов 404, у которых просто нет данных (элемент не найден). В отличие от 404, код 418 не бросается никаким промежуточным софтом. Альтернатива — использовать для обозначения ситуаций «элемент не найден» 410 Gone , но это не совсем корректно, т.к. предполагает, что ресурс когда-то существовал. Да и выделить баги клиента из потока 404 будет сложнее.

419 Authentication Timeout

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

422 Unprocessable Entity

Запрос корректно разобран, но содержание запроса не прошло серверную валидацию.

Например, в теле запроса были указаны неизвестные серверу поля, или не были указаны обязательные, или с содержимым полей что-то не так.

Обычно это означает ошибку в введённых пользователем данных, но может также быть вызвано ошибкой на клиенте или несовпадением версий.

500 Internal Server Error

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

Всё, что может сделать клиент в этом случае — это уведомить пользователя и сделать console.error(err) для более продвинутых товарищей (админов, разработчиков и тестировщиков).

501 Not Implemented

Возвращается, если текущий метод неприменим (не реализован) к объекту запроса.

Варианты отправки запросов

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

В этом разделе мы приведем несколько разных примеров кода, как можно отправлять запросы к REST API.

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

Как сделать внутренний запрос к REST API из плагина?
Запрос с помощью Fetch в JavaScript
Запрос с помощью jQuery AJAX

Как сделать внутренний запрос к REST API из плагина?

Это можно сделать с помощью функции rest_do_request(). Она создает запрос к API внутри WordPress, т.е. технически запроса не происходит:

Запрос с помощью Fetch в JavaScript

Fetch — это веб-api, который призван заменить оригинальный метод XMLHTTPRequests для работы с AJAX и HTTP запросами. Fetch поддерживается в последних версиях современных браузеров: см. полифилл по этой ссылке, если он нужен.

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

В обоих примерах сначала выбрасываем ошибку (throw), если статус ответа не 200. Если ошибки нет, то превращаем ответ в json и обрабатываем его.

В конце ловим с помощью .catch() любые выброшенные нами ошибки.

Запрос с помощью jQuery AJAX

Пример JS кода на основе jQuery.

$.ajax автоматически преобразует JSON ответ в массив или объект JavaScript. Поэтому тут не нужны дополнительные преобразования, можно сразу работать с ответом, как будто это объект или массив JavaScript.