Структура мини-курса
До сих пор мы узнали, какие есть популярные протоколы для передачи данных, а также что 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: Основные и ключевые |