Структура мини-курса
-
Проверка подлинности API, часть 1: Основные и ключевые
-
Проверка подлинности API, часть 2: OAuth
-
Проектирование API
-
Взаимодействие с API в режиме реального времени
-
Реализация API
До сих пор мы узнали, какие есть популярные протоколы для передачи данных, а также что HTTP (протокол передачи гипертекста) (Hyper-Text Transfer Protocol) является основой API в сети и что для их использования нам нужно знать, как работает HTTP. В этой главе мы рассмотрим данные, предоставляемые API, как они форматируются и как HTTP делает это возможным.
Структура главы 3
Четыре типа API
Форматы данных API
JSON
XML
Как различные представления данных передаются в HTTP
Краткое содержание главы 3
Четыре типа API
API можно разделить на четыре типа или формата: внутренние, внешние, партнерские и составные. Формат API, который вы выберете, будет зависеть от его предполагаемой области применения и уникальных спецификаций вашего предполагаемого варианта использования. Вот как они сравниваются:
Внутренние (Internal): также называемые частными, эти API (как вы, вероятно, догадались) предназначены для соединения систем, размещенных в одной организации. Это удобный способ для растущих компаний оставаться гибкими в своих потребностях в данных и совместной работе.
Внешние (External): также называемые публичными (public API) или открытыми (open) API, внешние API (external APIs) доступны для общественности и могут быть легко доступны третьим лицам. Это удобно для общедоступных приложений и систем, которые предназначены для связи с внешними системами и приложениями.
Партнерские (Partner): эти API находятся где-то между внутренними и внешними. Они позволяют одной организации связывать свои данные только с заранее определенными и одобренными третьими лицами. Это помогает организациям связывать внутренние системы с указанными организациями или приложениями, такими как ERP. (ERPs).
Составные (Composite): разработчики могут снизить нагрузку на свои серверы, объединив несколько API в один вызов. Это может повысить скорость работы сервера или связать отдельные, но связанные API в один процесс.
Форматы данных API
При обмене данными с людьми возможности отображения информации ограничены только человеческим воображением. Вспомните пиццерию из прошлой главы — как они могли бы отформатировать свое меню? Это может быть маркированный список, состоящий только из текста, это может быть серия фотографий с подписями или это могут быть даже только фотографии.
Способ представления данных зависит от того, какой способ делает информацию наиболее простой для понимания целевой аудиторией.
Тот же принцип применяется при обмене данными между компьютерами. Один компьютер должен передавать данные в формате, который будет понятен другому. Как правило, это означает некое текстовое представление. Наиболее распространенными форматами, встречающимися в современных API, являются JSON (JavaScript Object Notation) и XML (Extensible Markup Language).
JSON
Многие API приняли новое представление JSON, поскольку оно построено на популярном языке программирования JavaScript, который повсеместно используется в Интернете и может использоваться как на фронтенде, так и на бэкенде веб-приложения или сервиса. JSON — очень простой формат, который выражается с помощью комбинации знаков препинания и реальных, читаемых слов. Каждый объект в JSON — заключенный в фигурные скобки ({}) — содержит две части, ключи и значения, каждая из которых заключена в кавычки («») и разделена двоеточием (:).
Ключи представляют атрибут описываемого объекта и указывают одно или несколько соответствующих значений. Например, если заказ пиццы является объектом, его атрибутами (ключами (keys)) будут тип корочки, начинки и статус заказа. Выборками для этих атрибутов/ключей (attributes/keys) будут опции (значения (values)), такие как толстая корочка, пепперони и доставка, соответственно.
Давайте посмотрим, как этот заказ пиццы мог бы выглядеть в формате JSON:
В приведенном выше примере в формате JSON ключами являются слова слева от двоеточий: «начинка» (toppings), «корочка» (crust) и «статус» (status). Они сообщают нам, какие атрибуты содержит заказ пиццы. Значениями являются части, расположенные справа от двоеточий. Это фактические детали заказа.
Если читать строчку слева направо, получится вполне естественное английское предложение. Взяв в качестве примера первую строчку, мы могли бы прочитать ее так: «Корж (корочка) для этой пиццы выполнен в оригинальном стиле«. Вторую строку также можно прочитать следующим образом — в формате JSON в квадратных скобках ([]) указывается список значений или массив. Итак, мы читаем вторую строку заказа следующим образом: «Начинки для этого заказа: сыр, пепперони и чеснок«.
Иногда вы можете захотеть использовать объект в качестве значения ключа. Давайте расширим наш заказ пиццы информацией о клиенте, чтобы вы могли видеть, как это может выглядеть:
В этой обновленной версии мы видим, что добавлен новый ключ «клиент«. Значение этого ключа представляет собой другой набор ключей и значений, которые предоставляют подробную информацию о клиенте, разместившем заказ. Классный трюк, да? Это называется ассоциативным массивом. Однако пусть вас не пугает этот технический термин — ассоциативный массив — это всего лишь вложенный объект.
XML
XML существует с 1996 года. Со временем он стал очень зрелым и мощным форматом данных. Как и JSON, XML предоставляет несколько простых строительных блоков, которые разработчики API используют для структурирования своих данных, выраженных словами и знаками препинания. Основной строительный блок XML называется узлом (node), и каждый узел представляет данные в тегах и значениях, похожих на ключи и значения JSON.
Давайте посмотрим, как может выглядеть наш заказ пиццы в XML:
XML всегда начинается с корневого узла, который в нашем примере с пиццей представлен тегом «order«. Узлы всегда открываются тегом внутри скобок «меньше, чем» (less-than) (<) и «больше, чем» (greater-than)(>), а затем закрываются тем же тегом с «косой чертой» (slash) (/) спереди, содержащим каждый узел (называемый «дочерними узлами» (child nodes)) между ними.
В примере с пиццей каждый тег обозначает определенный атрибут заказа (например, ключ в JSON), а данные между открывающим и закрывающим тегами представляют собой связанную информацию (например, значение в JSON)
На примере выше, показан фрагмент XML, где:
• node opening tag (узел открытия тега) = <crust>
• values (значение) = original
• node closing tag (узел закрытия тега) = </crust>
Вы также можете составить предложения на английском языке, прочитав XML. Взглянув на строку с надписью «корж«, мы можем прочитать: «Корж для пиццы — это оригинальный стиль» («The crust for the pizza is original style.»). Обратите внимание, что в XML каждый элемент в списке начинок помечен тегами. Вы можете видеть, что для передачи данных в формате XML требуется гораздо больше текста, чем в формате JSON.
Как различные представления данных передаются в HTTP
Теперь, когда мы изучили некоторые доступные форматы данных, нам нужно знать, как использовать их в HTTP. Для этого мы снова поприветствуем одну из основ HTTP: заголовки. В Главе 2 мы узнали, что заголовки — это список информации о запросе или ответе. Существует заголовок для указания того, в каком представлении находятся данные: Content-Type.
Когда клиент отправляет заголовок Content-Type в запросе, он сообщает серверу, что данные в теле запроса отформатированы определенным образом. Если клиент хочет отправить серверу данные JSON, он установит Content-Type на «application/json«. Получив запрос и увидев этот Content-Type, сервер сначала проверит, понимает ли он этот формат, и если да, то узнает, как читать данные. Аналогично, когда сервер отправляет клиенту ответ, он также установит Content-Type, чтобы сообщить клиенту, как читать тело ответа.
Иногда клиент может говорить только об одном формате данных. Если сервер отправляет обратно что-либо, отличное от этого формата, клиент терпит неудачу и выдает ошибку. К счастью, на помощь приходит второй заголовок HTTP. Клиент может установить заголовок Accept, чтобы сообщить серверу, какие форматы данных он может принимать. Если клиент может говорить только в формате JSON, он может установить заголовок Accept на «application/json». Затем сервер отправит свой ответ в формате JSON. Если сервер не поддерживает формат, запрашиваемый клиентом, он может отправить клиенту сообщение об ошибке, чтобы дать ему знать, что запрос не будет работать.
Благодаря этим двум заголовкам, Content-Type и Accept, клиент и сервер могут работать с форматами данных, которые они понимают и которые им необходимы для корректной работы.
Краткое изложение главы 3
В этой главе мы узнали, что для того, чтобы два компьютера могли общаться, они должны понимать передаваемые им данные. Мы познакомились с двумя распространенными форматами данных, используемыми API: JSON и XML. Мы также узнали, что заголовок HTTP Content—Type является полезным способом указать, какой формат данных отправляется в запросе, а заголовок Accept указывает запрошенный формат для ответа.
Ключевыми терминами, которые мы изучили, были:
JSON: обозначение объекта в JavaScript
Объект (Object): предмет или существительное (человек, заказ пиццы…)
Ключ (Key): атрибут объекта (цвет, начинка…)
Значение (Value): значение атрибута (синий, пепперони…)
Ассоциативный массив (Associative array): вложенный объект
XML: Расширяемый язык разметки
Следующая
В следующей главе мы узнаем, как два компьютера могут установить доверительные отношения с помощью аутентификации для передачи конфиденциальных данных, таких как сведения о клиентах или личный контент.
|
Предыдущая глава: |
Следующая глава: Глава 4. Проверка подлинности API, часть 1: Основные и ключевые |
ссылка на оригинал статьи https://habr.com/ru/articles/891358/
Добавить комментарий