API: что это и как работает простыми словами

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

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

Что такое API

API расшифровывается как Application Programming Interface — «интерфейс программирования приложений».

Проще всего представить API как официанта в ресторане:

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

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

Например, сайт с расписанием рейсов не хранит данные обо всех самолётах самостоятельно. Он может отправить запрос в API авиакомпании и получить актуальные данные: время вылета, номер рейса, статус и терминал.

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

Как работает API

Веб-API обычно работает по схеме запрос → обработка → ответ.

Приложение отправляет запрос на адрес API.
API проверяет, кто делает запрос и есть ли у него доступ.
Сервер обрабатывает команду: ищет данные, создаёт заказ, отправляет сообщение или выполняет другое действие.
Сервер формирует ответ.
Приложение получает ответ и показывает результат пользователю.

Допустим, приложение хочет получить данные о курсе валют. Оно отправляет запрос:

GET https://api.example.com/v1/rates?base=RUB

Сервер может ответить так:

{
  "base": "RUB",
  "rates": {
    "USD": 0.0127,
    "EUR": 0.0117
  },
  "updatedAt": "2026-07-05T12:00:00Z"
}

Приложение читает этот JSON и выводит пользователю нужные цифры в удобном интерфейсе.

Из чего состоит API-запрос

У большинства API-запросов есть несколько основных частей.

1. URL и endpoint

URL — адрес сервера.
Endpoint — конкретная точка API, которая отвечает за определённую задачу.

Например:

https://api.example.com/v1/users/42

Здесь:

https://api.example.com — адрес API;
/v1 — версия API;
/users — раздел с пользователями;
/42 — конкретный пользователь с идентификатором 42.

Один API может иметь десятки endpoint-ов: для пользователей, заказов, товаров, сообщений, платежей и других сущностей.

2. HTTP-метод

Метод показывает, что именно нужно сделать с данными.

Метод	Что делает	Пример
`GET`	Получает данные	Показать список товаров
`POST`	Создаёт новые данные	Оформить заказ
`PUT` / `PATCH`	Изменяет данные	Обновить имя пользователя
`DELETE`	Удаляет данные	Удалить сохранённый адрес

Например, два запроса могут идти на один и тот же endpoint, но выполнять разные действия:

GET /v1/orders/125

Получит заказ №125.

DELETE /v1/orders/125

Попытается удалить заказ №125.

3. Параметры

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

GET /v1/products?category=phones&limit=20

В этом примере API должен вернуть до 20 товаров из категории phones.

Есть и параметры в пути:

GET /v1/products/128

Здесь 128 — ID конкретного товара.

4. Заголовки

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

Пример:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

Самый важный заголовок во многих API — Authorization. Он сообщает серверу, от имени кого выполняется запрос и есть ли у этого пользователя нужные права.

5. Тело запроса

Тело (body) используют, когда нужно отправить данные на сервер: создать аккаунт, изменить профиль, оформить заказ.

Например, при создании пользователя:

{
  "name": "Анна",
  "email": "anna@example.com"
}

Такой JSON обычно отправляется методом POST.

В каком формате API возвращает данные

Самый популярный формат — JSON. Он компактный, понятный человеку и легко обрабатывается в JavaScript, Python, PHP, Go и других языках.

Пример ответа API:

{
  "id": 42,
  "name": "Анна",
  "plan": "premium",
  "active": true
}

Раньше часто использовали XML, а в некоторых системах он встречается до сих пор. Но для современных веб- и мобильных API JSON стал стандартом де-факто.

Коды ответа API

Вместе с данными сервер возвращает HTTP-статус. По нему приложение понимает, прошёл ли запрос успешно.

Код	Значение
`200 OK`	Всё прошло успешно
`201 Created`	Данные успешно созданы
`400 Bad Request`	В запросе ошибка: не хватает поля или передан неверный формат
`401 Unauthorized`	Нужна авторизация или токен недействителен
`403 Forbidden`	Авторизация есть, но прав недостаточно
`404 Not Found`	Нужный объект или endpoint не найден
`429 Too Many Requests`	Слишком много запросов за короткое время
`500 Internal Server Error`	Ошибка на стороне сервера

Например, если API вернул 401, приложение обычно предлагает войти в аккаунт заново. Если вернулся 429, оно может подождать и повторить запрос позже.

Не ориентируйтесь только на текст ошибки. Всегда проверяйте HTTP-статус и тело ответа: хороший API возвращает понятное описание проблемы, например поле с ошибкой message или code.

REST API, GraphQL и Webhooks — в чём разница

API — это общее понятие. REST, GraphQL и Webhooks — разные способы организовать взаимодействие сервисов.

REST API

REST — самый распространённый подход. У него есть отдельные endpoint-ы для разных сущностей, а действия выполняются HTTP-методами.

Пример:

GET /v1/users
GET /v1/users/42
POST /v1/users
DELETE /v1/users/42

REST легко понять, поэтому он широко используется в сайтах, мобильных приложениях, CRM и интернет-магазинах.

GraphQL

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

Например, приложение может попросить только имя пользователя и его аватар, а не весь профиль целиком.

Webhooks

Webhook работает в обратную сторону: не ваше приложение спрашивает сервер «что нового?», а сервер сам отправляет уведомление, когда происходит событие.

Например, платёжный сервис может отправить webhook на ваш сайт после успешной оплаты. Так магазин узнает об оплате сразу, без постоянных проверок статуса.

Как API защищают данные

Открытый endpoint без ограничений подойдёт только для публичной информации: например, списка стран или курса валют. Когда API работает с аккаунтами, платежами или персональными данными, нужна защита.

Самые распространённые способы авторизации:

API key — постоянный ключ для доступа к API;
Bearer token — временный токен, который передают в заголовке Authorization;
OAuth 2.0 — безопасный вход через сторонний сервис, например Google или Telegram;
JWT — токен с данными о пользователе и сроком действия.

Главное правило: никогда не храните секретный API-ключ в коде сайта, который загружается в браузер. Его смогут увидеть другие пользователи. Секретные ключи должны находиться на сервере или в защищённых переменных окружения.

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

Простой пример API на JavaScript

Ниже — типичный запрос из сайта или приложения. Код отправляет запрос, проверяет ответ и выводит полученные данные.

async function getUser(userId) {
  const response = await fetch(
    `https://api.example.com/v1/users/${userId}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
        Accept: "application/json"
      }
    }
  );
 
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
 
  return response.json();
}
 
getUser(42)
  .then((user) => console.log(user.name))
  .catch((error) => console.error(error.message));

В реальном проекте адрес API, ключ и обработка ошибок будут зависеть от конкретного сервиса. Но базовая логика почти всегда одна: отправить запрос, проверить статус, разобрать JSON, обработать ошибку.

Где API используется каждый день

API работает в большинстве привычных сервисов:

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

Пользователь видит только кнопки и экраны, но между ними постоянно идут API-запросы.

Частые ошибки при работе с API

Неверный URL или метод

Если endpoint указан неправильно, сервер обычно вернёт 404. Если для создания данных отправить GET вместо POST, API может ответить 405 Method Not Allowed или другой ошибкой.

Нет авторизации

Ошибка 401 Unauthorized означает, что токен отсутствует, просрочен или неверен. Проверьте заголовок Authorization и срок действия токена.

Недостаточно прав

Даже с рабочим токеном можно получить 403 Forbidden. Например, обычный пользователь не может удалить чужой аккаунт, а тестовый ключ не имеет доступа к боевым платежам.

Слишком много запросов

У API часто есть лимиты, чтобы защитить сервис от перегрузки. При 429 Too Many Requests не нужно отправлять запрос повторно каждую миллисекунду — лучше использовать паузу и повторную попытку с увеличивающимся интервалом.

Доверие данным без проверки

Нельзя считать, что данные от внешнего API всегда корректны. Проверяйте типы полей, обязательные значения и ошибки. Особенно это важно для платежей, заказов и данных пользователей.

Вывод

API — это договорённость, по которой программы общаются друг с другом. Одна система отправляет понятный запрос, другая возвращает структурированный ответ. Благодаря этому сайты, приложения, боты и сервисы могут использовать данные и возможности друг друга без доступа к внутреннему устройству.

Чтобы начать работать с API, достаточно разобраться с пятью вещами: URL, HTTP-методами, параметрами, авторизацией и JSON. Дальше всё зависит от документации конкретного сервиса.

Другие материалы о технологиях →