API-запросы¶

API-запрос — это обращение программы или сервиса к программному интерфейсу (API) с целью получить данные, выполнить операцию или вызвать функцию. Запрос формируется по определённым правилам: содержит адрес ресурса, метод, заголовки и, при необходимости, тело. API-запросы лежат в основе работы веб-приложений, мобильных клиентов, микросервисных архитектур и интеграций между информационными системами.

¶Структура запроса

Стандартный HTTP-запрос к API состоит из нескольких частей:

¶Методы HTTP

Основные HTTP-методы, используемые в REST API:

• GET — получение данных. Идемпотентен: повторный вызов не меняет состояние сервера.
• POST — создание нового ресурса или выполнение операции. Не идемпотентен.
• PUT — полное обновление ресурса. Идемпотентен.
• PATCH — частичное обновление ресурса.
• DELETE — удаление ресурса. Идемпотентен.

¶Форматы данных

Чаще всего тело запроса и ответа передаётся в формате JSON — текстовом формате обмена данными на основе JavaScript. Альтернативы: XML, YAML, Protocol Buffers, MessagePack. Формат данных указывается в заголовке Content-Type (например, application/json).

¶Типы API

По способу организации доступа API делятся на несколько типов:

• REST (Representational State Transfer) — архитектурный стиль, основанный на HTTP-методах и URL-адресах ресурсов. Наиболее распространён в веб-разработке.
• SOAP — протокол обмена сообщениями на базе XML с жёсткой спецификацией WSDL. Применяется в банковских и государственных системах.
• GraphQL — язык запросов, позволяющий клиенту запрашивать ровно те данные, которые нужны, одним запросом. Разработан компанией Meta (признана экстремистской и запрещена в РФ) в 2015 году.
• gRPC — RPC-фреймворк от Google, использующий Protocol Buffers и HTTP/2. Популярен в микросервисных архитектурах.
• WebSocket — протокол двустороннего обмена сообщениями в реальном времени поверх TCP.

¶Аутентификация

Для доступа к защищённым API используются механизмы аутентификации:

• API-ключи — простые токены, передаваемые в заголовке.
• OAuth 2.0 — протокол делегированной авторизации, выдающий временные токены доступа.
• JWT (JSON Web Token) — самоподписанные токены с утверждениями о пользователе.
• Подписи запросов — HMAC-подпись тела запроса секретным ключом (применяется в платёжных API).

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

API возвращает коды HTTP-статуса, характеризующие результат запроса:

• 2xx — успех (200 OK, 201 Created).
• 4xx — ошибка на стороне клиента (400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests).
• 5xx — ошибка на стороне сервера (500 Internal Server Error, 503 Service Unavailable).

Тело ответа при ошибке обычно содержит структурированное описание: код ошибки, сообщение, детали.

¶Инструменты для работы с запросами

Для отправки и отладки API-запросов применяются:

• curl — консольная утилита, доступная в большинстве ОС.
• Postman — графический клиент для проектирования и тестирования API.
• Insomnia — альтернатива Postman с упором на REST и GraphQL.
• HTTPie — утилита с человекочитаемым синтаксисом.
• Языки программирования — библиотеки requests (Python), axios (JavaScript), HttpClient (.NET), Retrofit (Android).

¶Ограничение частоты запросов

Чтобы защитить сервер от перегрузки и злоупотреблений, API реализуют rate limiting — ограничение числа запросов за единицу времени. Клиент, превысивший лимит, получает ответ 429 Too Many Requests с заголовком Retry-After. Распространённые алгоритмы: фиксированное окно, скользящее окно, алгоритм «ведро» (token bucket).

¶Кэширование

Для снижения нагрузки ответы API кэшируются. Механизмы:

• HTTP-кэширование — через заголовки Cache-Control, ETag, Last-Modified.
• Прикладное кэширование — на уровне приложения (Redis, Memcached).

Клиент может принудительно обновить кэш, добавив заголовок Cache-Control: no-cache.

¶История

Первые публичные API появились в начале 2000-х годов: eBay (2000), Amazon (2002), Google Maps (2005). Термин «Web API» закрепился с развитием REST-архитектуры, описанной Ройом Филдингом в диссертации 2000 года. В России широкое распространение получили API государственных услуг (Госуслуги), банковских систем и платёжных шлюзов.

¶Источники

• Рой Филдинг. «Architectural Styles and the Design of Network-based Software Architectures», 2000
• Мартина Фаулера. «Patterns of Enterprise Application Architecture», 2002
• RFC 9110 — HTTP Semantics
• Документация MDN Web Docs по HTTP-методам
• «RESTful Web APIs» Ричардасон и Амундсена, 2013