Глава 2: API-протоколы. Мини-курс API-интерфейсы для самых маленьких

Структура мини-курса Мини-курс API-интерфейсы для самых маленьких.

1. Введение в API

2. Протоколы API

3. Типы и форматы API

4. Проверка подлинности API, часть 1: Основные и ключевые

5. Проверка подлинности API, часть 2: OAuth

6. Проектирование API

7. Взаимодействие с API в режиме реального времени

8. Реализация API

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

Структура главы 2

1. Протоколы обмена данными

2. Популярные API-протоколы

3. Сравнение API-протоколов

4. HTTP: Web — протоколы

5. HTTP requests (HTTP протокол запроса)

6. URL

7. Method (Методы)

8. Headers (Заголовки)

9. Body (Тело запроса)

10. HTTP responses (HTTP-ответы)

11. Status codes (Коды статуса)

12. Как API строятся на HTTP

13. Краткое изложение главы 2

---

Глава 2. API-протоколы

Часть 1. Популярные протоколы обмена данными

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

У компьютеров похожий этикет, хотя он и обозначается термином «протокол«. Компьютерный протокол — это общепринятый набор правил, которые определяют, как два компьютера могут общаться друг с другом. Однако, по сравнению с нашими стандартами, компьютерный протокол является чрезвычайно жестким. Задумайтесь на минутку о двух предложениях «Мой любимый цвет — синий» и «Синий — мой любимый цвет«. Люди способны разобрать каждое предложение и увидеть, что они означают одно и то же несмотря на то, что слова расположены в разном порядке. К сожалению, компьютеры не настолько умны.

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

Например: Вы можете представить это как запрос человеком почтового адреса. Когда вы спрашиваете о местоположении какого-либо объекта, вы предполагаете, что первое, что вам скажут, — это адрес улицы, за которым следуют город, штат и, наконец, почтовый индекс. У вас также есть определенные требования к каждой части адреса, например, к тому, что почтовый индекс должен состоять только из цифр.

Аналогичный уровень детализации требуется для работы компьютерного протокола.

Протоколы обмена данными — это наборы правил и стандартов, которые определяют, как устройства взаимодействуют между собой в сети. Они обеспечивают корректную передачу, прием и интерпретацию данных.

Вот основные категории и примеры протоколов:

1. Сетевые протоколы

Используются для передачи данных между устройствами в сети.

• IP (Internet Protocol) — отвечает за адресацию и маршрутизацию пакетов данных.

• TCP (Transmission Control Protocol) — обеспечивает надежную передачу данных с установлением соединения.

• UDP (User Datagram Protocol) — более быстрый, но менее надежный протокол без установления соединения.

• ICMP (Internet Control Message Protocol) — используется для диагностики и управления сетевыми соединениями (например, ping).

2. Протоколы прикладного уровня

Определяют, как приложения взаимодействуют между собой.

• HTTP/HTTPS (HyperText Transfer Protocol) — для передачи веб-страниц и данных (HTTPS — защищенная версия с шифрованием).

• FTP (File Transfer Protocol) — для передачи файлов.

• SMTP (Simple Mail Transfer Protocol) — для отправки электронной почты.

• POP3/IMAP — для получения электронной почты.

• DNS (Domain Name System) — преобразует доменные имена в IP-адреса.

• WebSocket — для двустороннего обмена данными в реальном времени.

3. Транспортные протоколы

Обеспечивают доставку данных между приложениями.

• TCP — гарантирует надежную доставку данных.

• UDP — используется для быстрой передачи данных без гарантии доставки.

4. Протоколы маршрутизации

Используются для определения оптимального пути передачи данных.

• RIP (Routing Information Protocol) — простой протокол маршрутизации.

• OSPF (Open Shortest Path First) — более сложный и эффективный протокол.

• BGP (Border Gateway Protocol) — используется для маршрутизации между

5. Протоколы безопасности

Обеспечивают защиту данных при передаче.

• SSL/TLS (Secure Sockets Layer / Transport Layer Security) — для шифрования данных (используется в HTTPS).

• IPSec (Internet Protocol Security) — для защиты IP-пакетов.

• SSH (Secure Shell) — для безопасного удаленного доступа.

6. Беспроводные протоколы

Используются в беспроводных сетях.

• Wi-Fi (IEEE 802.11) — для беспроводной передачи данных.

• Bluetooth — для обмена данными между устройствами на коротких расстояниях.

• Zigbee — для IoT-устройств.

7. Протоколы для IoT (Интернета вещей)

Оптимизированы для устройств с ограниченными ресурсами.

• MQTT (Message Queuing Telemetry Transport) — для обмена сообщениями между устройствами.

• CoAP (Constrained Application Protocol) — для работы с ограниченными ресурсами.

• LoRaWAN — для передачи данных на большие расстояния с низким энергопотреблением.

8. Протоколы для работы с базами данных

Используются для взаимодействия с СУБД.

• SQL (Structured Query Language) — стандартный язык запросов.

• ODBC/JDBC — протоколы для подключения к базам данных.

9. Мультимедийные протоколы

Для передачи аудио и видео.

• RTP (Real-time Transport Protocol) — для передачи мультимедиа в реальном времени.

• RTSP (Real-Time Streaming Protocol) — для управления потоковым вещанием.

• WebRTC — для видеозвонков и обмена данными в браузерах.

10. Другие популярные протоколы

Другие популярные протоколы

• SNMP (Simple Network Management Protocol) — для управления сетевыми устройствами.

• NTP (Network Time Protocol) — для синхронизации времени.

• DHCP (Dynamic Host Configuration Protocol) — для автоматической настройки IP-адресов.

• и другие

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

---

Часть 2. Популярные API-протоколы

Протоколы обмена данными для API (Application Programming Interface) определяют, как клиенты взаимодействуют с серверами для получения или отправки данных. Они обеспечивают стандартизированный способ обмена информацией между различными системами. Вот основные протоколы, используемые для API:

1. HTTP/HTTPS (HyperText Transfer Protocol)

Самый распространенный протокол для веб-API.

• HTTP — используется для передачи данных в текстовом формате.

• HTTPS — защищенная версия HTTP с шифрованием (SSL/TLS).

• Методы HTTP:

  • GET — запрос данных.

  • POST — отправка данных.

  • PUT — обновление данных.

  • DELETE — удаление данных.

  • PATCH — частичное обновление данных.

• Форматы данных:

  • JSON (наиболее популярный).

  • XML.

  • Формы (form-data).

• Пример: RESTful API.

2. REST (Representational State Transfer)

Архитектурный стиль, основанный на HTTP.

• Основные принципы:

  • Использование HTTP-методов (GET, POST, PUT, DELETE).

  • Статусные коды (200, 404, 500 и т.д.).

  • Ресурсы идентифицируются через URL.

  • Данные передаются в формате JSON или XML.

• Пример: GET /api/users/1 — получение информации о пользователе с ID 1.

3. SOAP (Simple Object Access Protocol)

Протокол для обмена структурированными сообщениями.

• Особенности:

  • Использует XML для передачи данных.

  • Работает поверх HTTP, SMTP или других протоколов.

  • Поддерживает строгую типизацию и безопасность (WS-Security).

  • Более сложный и тяжеловесный по сравнению с REST.

• Пример: Веб-сервисы в корпоративных приложениях.

4. GraphQL

Язык запросов для API, разработанный Facebook.

• Особенности:

  • Позволяет клиенту запрашивать только нужные данные.

  • Использует единую конечную точку (endpoint).

  • Данные возвращаются в формате JSON.

  • Поддерживает сложные запросы и агрегацию данных.

• Пример:

  

  query {  user(id: 1) {    name    email  } }

5. gRPC (Google Remote Procedure Call)

Высокопроизводительный протокол для удаленного вызова процедур.

• Особенности:

  • Использует HTTP/2 для передачи данных.

  • Поддерживает бинарный формат (Protocol Buffers).

  • Обеспечивает высокую производительность и низкую задержку.

  • Подходит для микросервисов и реального времени.

• Пример: Взаимодействие между микросервисами.

6. WebSocket

Протокол для двустороннего обмена данными в реальном времени.

• Особенности:

  • Устанавливает постоянное соединение между клиентом и сервером.

  • Подходит для чатов, уведомлений и онлайн-игр.

  • Использует текстовый или бинарный формат данных.

• Пример: API для чат-приложений.

7. MQTT (Message Queuing Telemetry Transport)

Протокол для обмена сообщениями в IoT.

• Особенности:

  • Легковесный и энергоэффективный.

  • Использует модель «издатель-подписчик».

  • Подходит для устройств с ограниченными ресурсами.

• Пример: Управление IoT-устройствами.

8. Webhook

Механизм для отправки данных в реальном времени.

• Особенности:

  • Сервер отправляет данные на указанный URL при наступлении события.

  • Использует HTTP-запросы (обычно POST).

• Пример: Уведомления о платежах или изменениях в системе.

9. JSON-RPC и XML-RPC

Протоколы для удаленного вызова процедур.

• JSON-RPC:

  • Использует JSON для передачи данных.

  • Легковесный и простой.

• XML-RPC:

  • Использует XML для передачи данных.

  • Более старый и менее популярный.

• Пример: {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}.

10. OData (Open Data Protocol)

Стандарт для создания и потребления API.

• Особенности:

  • Основан на REST.

  • Поддерживает сложные запросы (фильтрация, сортировка, пагинация).

  • Использует JSON или XML.

• Пример: GET /api/products?$filter=Price gt 100.

11. AMQP (Advanced Message Queuing Protocol)

Протокол для обмена сообщениями между системами.

• Особенности:

  • Подходит для асинхронной передачи данных.

  • Используется в системах очередей (например, RabbitMQ).

• Пример: Обработка задач в фоновом режиме.

12. CoAP (Constrained Application Protocol)

Протокол для устройств с ограниченными ресурсами (IoT).

• Особенности:

  • Легковесный аналог HTTP.

  • Использует UDP вместо TCP.

• Пример: Управление IoT-устройствами.

---

Часть 3. Сравнение API-протоколов

Выбор протокола зависит от задач, требований к производительности, безопасности и сложности реализации. Например, REST подходит для большинства веб-API, gRPC — для высоконагруженных систем, а GraphQL — для гибких запросов.

---

Часть 4. HTTP: Web — протоколы

Вспомним, что практически для всего существует свой протокол, каждый из которых адаптирован для различных задач. Возможно, вы уже слышали о некоторых из них: Bluetooth для подключения устройств и POP или IMAP для получения электронной почты.

В Интернете основным протоколом является, протокол передачи гипертекста, более известный под своим сокращением HTTP. Когда вы вводите адрес типа http://example.com в веб-браузере, «http» указывает браузеру использовать правила HTTP при общении с сервером.

С повсеместным распространением HTTP в Интернете, многие компании решают использовать его в качестве протокола, лежащего в основе их API. Одним из преимуществ использования знакомого протокола является то, что он упрощает процесс обучения разработчиков, что стимулирует использование API. Еще одним преимуществом является то, что HTTP имеет несколько функций, полезных для создания хорошего API, как мы увидим позже. А сейчас давайте посмотрим, как работает HTTP!

---

Часть 5. HTTP requests (HTTP протокол запроса)

Взаимодействие в протоколе HTTP строится вокруг концепции, называемой Циклом Запрос-Ответ (the Request-Response Cycle). Клиент отправляет серверу запрос на выполнение чего-либо (Send request). Сервер, в свою очередь, отправляет клиенту ответ (Return response), сообщающий, может ли сервер сделать то, что запросил клиент.

Чтобы сделать действительный запрос, клиенту необходимо указать четыре вещи:

1. URL (единый указатель ресурсов) (Uniform Resource Locator)

2. Метод (Method). Стандартные методы API позволяют выполнять CRUD-операции: создавать, получать, изменять и удалять ресурсы.

3. Список заголовков (Headers) = (List of headers)

4. Тело (Body)

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

Спецификация HTTP на самом деле требует, чтобы запрос содержал URI (универсальный идентификатор ресурса) (Uniform Resource Identifier), подмножеством которого являются URL-адреса (единые указатели ресурсов), наряду с URN (унифицированными именами ресурсов) (Uniform Resource Name). Мы выбрали URL, потому что это аббревиатура, которую читатели уже знают. Тонкие различия между этими тремя аспектами выходят за рамки данного курса.

---

Часть 6. URL

URL-адреса знакомы нам по ежедневному использованию Интернета, но задумывались ли вы когда-нибудь об их структуре? В HTTP URL-адрес — это уникальный адрес для объекта (существительного). Какие объекты получают адреса, полностью зависит от компании, управляющей сервером. Они могут создавать URL-адреса для веб-страниц, изображений или даже видеороликов с милыми животными.

API-интерфейсы расширяют эту идею и включают в нее такие существительные, как клиенты, продукты и твиты. При этом URL-адреса становятся для клиента простым способом сообщить серверу, с чем он хочет взаимодействовать. Конечно, API-интерфейсы также не называют их «вещами» (things), а дают им техническое название «ресурсы» (resources).

---

Часть 7. Method (Методы)

Метод запроса сообщает серверу, какого рода действия клиент хочет, чтобы сервер выполнил. Фактически, метод обычно называют «глаголом» запроса.

Вот некоторые из наиболее распространенных методов API:

• GET: просит сервер извлечь ресурс

• POST: просит сервер создать новый ресурс

• PUT: просит сервер отредактировать/обновить существующий ресурс

• DELETE: просит сервер удалить ресурс

• PATCH: просит сервер частично отредактировать/обновить существующий ресурс

• HEAD: Запрос заголовков ответа без тела.

• OPTIONS: Запрос поддерживаемых методов для ресурса.

• CONNECT: Установка туннеля к серверу.

• TRACE: Возвращает полученный запрос (для отладки).

Вот пример, иллюстрирующий эти методы. Допустим, есть пиццерия с API, который вы можете использовать для размещения заказов. Вы размещаете заказ, отправляя запрос POST на сервер ресторана с данными вашего заказа, прося их создать вашу пиццу. Однако, как только вы отправляете запрос, вы понимаете, что выбрали неправильный стиль корочки, поэтому вы делаете запрос PATCH, чтобы изменить только стиль корочки (crust) (в отличие от запроса PUT, который вы использовали бы для изменения всего ресурса/заказа).

Ожидая свой заказ, вы отправляете множество запросов GET, чтобы проверить его статус. После часа ожидания вы решаете, что с вас хватит, и инициируете запрос DELETE, чтобы отменить заказ и удалить его из системы.

---

Часть 8. Headers (Заголовки)

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

Каждый раз, когда вы посещаете веб-сайт на своем смартфоне, который был специально обработан для мобильных устройств, это форматирование становится возможным благодаря HTTP—заголовку под названием «User-Agent» (Пользователь—Агент). Клиент использует этот заголовок, чтобы сообщить серверу, какой тип устройства вы используете, и веб-сайты, достаточно умные, чтобы определить это, могут отправить вам наилучший формат для вашего устройства.

Существует множество HTTP—заголовков, с которыми взаимодействуют клиенты и серверы. Однако мы не будем рассматривать их все сразу, а уделим им внимание в следующих главах, когда они станут более актуальными.

---

Часть 9. Body (Тело запроса)

Тело-запроса содержит данные, которые клиент хочет отправить серверу. Продолжая наш пример с заказом пиццы, приведенный выше, в Теле-запроса указываются детали заказа.

Уникальной чертой тела является то, что клиент имеет полный контроль над этой частью запроса. В отличие от метода (Method), URL или заголовков (Headers), где протокол HTTP требует жесткой структуры, тело запроса (Body) позволяет клиенту отправлять все, что ему нужно.

Эти четыре части — URL, метод (Method), заголовки (Headers) и тело запроса (Body) — составляют полный HTTP-запрос.

---

Часть 10. HTTP responses (HTTP-ответы)

После того как сервер получает запрос от клиента, он пытается выполнить его и отправляет ответ клиенту. HTTP-ответы имеют структуру, очень похожую на запросы. Основное отличие заключается в том, что вместо метода и URL в ответе указывается код состояния. Заголовки и тело ответа также соответствуют формату запросов.

Status codes (Коды статуса)

Коды состояния — это трехзначные числа, каждое из которых имеет уникальное значение. При правильном использовании в API это небольшое число может передавать клиенту много информации. Например, вы, возможно, видели эту страницу во время своих блужданий по Интернету:

• Код статуса этого ответа — 404, что означает «Не найдено». Всякий раз, когда клиент делает запрос на ресурс, который не существует, сервер отвечает кодом статуса 404, чтобы дать клиенту знать: «Этот ресурс не существует, поэтому, пожалуйста, не запрашивайте его снова!»

• В протоколе HTTP существует множество других статусов, включая 200 («успешно! запрос был выполнен») и 503 («наш веб-сайт/API в настоящее время недоступен»). Мы узнаем еще о нескольких из них, когда они появятся в последующих главах.

Внимание. Коды статуса HTTP используются для информирования клиента о результате выполнения запроса к серверу.

В контексте API, наиболее популярные коды статуса включают:

1. 200 OK — Запрос успешно выполнен, и сервер возвращает запрошенные данные.

2. 201 Created — Запрос успешно выполнен, и новый ресурс был создан (часто используется после POST-запросов).

3. 204 No Content — Запрос успешно выполнен, но сервер не возвращает никакого содержимого (например, после DELETE-запроса).

4. 400 Bad Request — Сервер не может обработать запрос из-за ошибки на стороне клиента (например, неверный синтаксис запроса).

5. 401 Unauthorized — Для доступа к ресурсу требуется аутентификация, и она не была предоставлена или не прошла проверку.

6. 403 Forbidden — Сервер понимает запрос, но отказывается его выполнять из-за ограничений доступа.

7. 404 Not Found — Запрашиваемый ресурс не найден на сервере.

8. 500 Internal Server Error — Сервер столкнулся с непредвиденной ошибкой, которая помешала ему выполнить запрос.

9. 502 Bad Gateway — Сервер, действуя как шлюз или прокси, получил недопустимый ответ от вышестоящего сервера.

10. 503 Service Unavailable — Сервер временно не может обработать запрос из-за перегрузки или технического обслуживания.

Эти коды статуса широко используются в API для информирования клиентов о результате их запросов.

---

Часть 11. Completing the cycle (Завершение цикла)

После доставки ответа клиенту цикл «запрос-ответ» завершается, и этот раунд коммуникации заканчивается. Теперь клиенту остается только инициировать дальнейшие взаимодействия. Сервер не будет отправлять клиенту никаких данных, пока не получит новый запрос.

---

Часть 12. Как API строятся на HTTP

К настоящему времени вы можете видеть, что HTTP поддерживает широкий спектр перестановок, которые помогают клиенту и серверу взаимодействовать. Итак, как это помогает нам в работе с API? Гибкость HTTP означает, что API, построенные на его основе, могут предоставить клиентам большой потенциал для бизнеса. Мы увидели этот потенциал в приведенном выше примере с заказом пиццы. Простая настройка метода запроса заключалась в том, чтобы указать серверу создать новый заказ или отменить существующий. Было легко превратить желаемый бизнес-результат в понятную серверу инструкцию. Очень эффективно!

Эта универсальность протокола HTTP распространяется и на другие части запроса. Некоторые API требуют определенного заголовка, в то время как другие требуют определенной информации внутри тела запроса. Возможность использовать API зависит от знания того, как сделать правильный HTTP-запрос, чтобы получить желаемый результат.

---

Часть 13

Краткое изложение главы 2

Целью этой главы было

1. Познакомить вас с протоколами обмена данными

2. Познакомить вас с протоколами используемыми в API

3. Дать вам базовое понимание HTTP. Ключевой концепцией был Цикл Запрос-Ответ, который мы разбили на следующие части:

• Request (Запрос): Состоит из URL (http://…), метода (a method) (GET, POST, PUT, PATCH, DELETE), списка заголовков (a list of headers) (User—Agent…), и тела (данных) (a body (data))

• Response (Ответ): Состоит из Статуса кода (a status code) (200, 404…), списка заголовков (a list of headers), и тела (данных) (a body (data))

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

---

Следующая

В следующей главе мы рассмотрим, какие типы данных API-интерфейсов передаются между клиентом и сервером.