API

Что такое API

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

Ключевая идея — сокрытие реализации. Сервис может переписать код, сменить базу данных или переехать на другие серверы; пока контракт прежний, клиенты продолжают работать без изменений.

API простыми словами

Аналогия — официант в ресторане. Вы не идёте на кухню готовить сами: выбираете блюдо из меню, официант передаёт заказ и приносит результат. Меню — документация API, заказ — запрос, блюдо — ответ. Кухня может полностью поменяться, но пока меню прежнее, заказывают так же.

Живые примеры: приложение погоды не измеряет температуру термометром, а спрашивает API метеосервиса; оплата картой в магазине — запрос к API платёжного провайдера; карта на сайте доставки — API картографического сервиса. «Апи» в русской речи — то же самое слово, просто произнесённое по буквам.

Как выглядит вызов API

Типичный веб-API работает поверх HTTP. Запрос — это метод и URI, ответ — код состояния и тело, чаще всего в JSON:

curl -s "https://api.example.com/v1/cities/moscow/weather" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

{
  "city": "moscow",
  "temperature_c": -3.2,
  "condition": "snow",
  "updated_at": "2026-01-17T09:00:00Z"
}

Конкретный адрес, к которому обращается клиент, называется API endpoint. Успех или неудачу клиент определяет по коду ответа: 200 — данные отданы, 401 — ключ неверный, 404 — такого города нет, 500 — сломался сам сервис.

Виды API

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

Различают также веб-API и библиотечные API: у любой библиотеки тоже есть API — набор публичных функций и классов. Но фраза «дёрнуть API» почти всегда означает сетевой вызов.

Что такое API-ключ

API-ключ — длинная случайная строка, которую клиент прикладывает к запросу, чтобы сервер понял, кто обращается, и посчитал лимиты и оплату. Обычно передаётся в заголовке Authorization: Bearer <ключ> или X-API-Key. Ключ равносилен паролю: его не кладут в репозиторий и не встраивают в код фронтенда. Подробности — на странице API-ключи; для пользовательских сессий вместо ключей чаще берут JWT или OAuth.

Telegram Bot API

Частый первый API в жизни разработчика — Telegram Bot API. Токен выдаёт @BotFather, дальше все методы вызываются как обычные HTTP-запросы:

curl "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -d chat_id=123456789 \
  -d text="Сервер поднялся"

Официальная документация — на английском, но методы простые и обёртки есть почти для всех языков. Подробный разбор — в статье Telegram-боты.

Как читать чужой API

• Документация. Хороший сервис публикует спецификацию Swagger / OpenAPI — там перечислены все эндпоинты, параметры и схемы ответов, а запрос можно отправить прямо из браузера.
• Лимиты. Почти любой публичный API ограничивает частоту запросов и отвечает 429, если перебрать.
• Что там на самом деле летит. Если документации нет, помогает вкладка Network в браузере и HAR-файл.
• Обратное направление. Когда события инициирует сервис, а не клиент, используют webhook — сервис сам шлёт HTTP-запрос вам.

Связанные термины

• REST API — самый распространённый стиль веб-API
• API endpoint — конкретный адрес вызова
• API-ключи — как API узнаёт вызывающего
• Swagger / OpenAPI — стандарт описания API
• HTTP — протокол, поверх которого работает большинство API
• Webhook — вызов в обратную сторону