API простыми словами: как сервисы разговаривают друг с другом

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

Общая картина: запрос, обработка и ответ

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

sequenceDiagram
    participant A as Клиент: сайт, бот или агент
    participant B as API
    participant C as Сервис или база данных
    A->>B: Запрос
    B->>C: Проверка и выполнение операции
    C->>B: Результат
    B->>A: Код состояния и данные

HTTP скрывает внутреннее устройство сервиса за единым интерфейсом. В типичном HTTP API клиенту нужно знать адрес ресурса, метод, параметры, формат данных и правила авторизации. Семантика HTTP-запросов и ответов определена в RFC 9110.

Где применяют API

• Сайт и система управления контентом: сайт получает опубликованные материалы через API.
• Бот и CRM: бот передаёт данные нового обращения в CRM.
• ИИ-агент и инструменты: агент читает разрешённые ресурсы или запускает доступные функции.
• Платёжный сценарий: сайт создаёт платёж и проверяет его состояние через API провайдера.
• Автоматизация: n8n или Make связывают несколько сервисов в один процесс.

REST, GraphQL, webhook и MCP: в чём разница

Эти понятия находятся на разных уровнях. REST описывает архитектурный стиль API. GraphQL — это язык запросов и среда выполнения для клиент-серверных приложений. Webhook служит механизмом доставки уведомлений о событиях. MCP (Model Context Protocol) задаёт протокол подключения приложений к контексту и инструментам языковых моделей.

В спецификации GraphQL предусмотрены запросы на чтение (query), изменения (mutation) и длительные подписки на события (subscription). Клиент выбирает поля ответа, но конкретная реализация сервиса определяет транспорт и адрес конечной точки. Подробнее: спецификация GraphQL, редакция September 2025.

MCP-сервер может предоставлять структурированные ресурсы и исполняемые функции, которые модель вызывает как инструменты. Наличие MCP само по себе не открывает всю внешнюю систему: доступные возможности и разрешения зависят от конкретной конфигурации сервера и подключения. Подробнее: спецификация MCP 2025-06-18.

REST API и HTTP-методы

В REST API адрес обычно указывает на ресурс, а метод выражает намерение запроса:

• GET /pages — получить представление списка страниц.
• POST /pages — передать данные для создания или иной обработки по правилам API.
• PATCH /pages/123 — частично изменить страницу, если API поддерживает PATCH.
• DELETE /pages/123 — запросить удаление страницы.

Смысл операции всегда проверяйте в документации конкретного API. Один и тот же HTTP-метод не гарантирует одинаковую бизнес-логику у разных сервисов.

Ответ часто сериализуется в JSON:

{
  "id": "123",
  "title": "Webhook простыми словами",
  "status": "Черновик",
  "created_at": "2026-05-11"
}

Аутентификация и управление доступом

API может проверять приложение, пользователя или оба субъекта. Распространённые механизмы:

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

Лимиты и безопасные повторные запросы

Лимиты зависят от сервиса и могут меняться. По данным документации Notion, проверенной 8 сентября 2026 года, Notion API применяет два ограничения:

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

При превышении лимита Notion возвращает HTTP 429. Временная перегрузка может сопровождаться ответом 529. Для обоих случаев документация предписывает учитывать заголовок Retry-After. Актуальные значения и правила проверяйте на странице Request limits.

Практическая схема обработки:

1. Направляйте исходящие запросы через очередь.
2. При 429 или 529 прочитайте Retry-After и выдержите указанную паузу.
3. При повторной ошибке увеличьте задержку экспоненциально и добавьте случайный разброс (jitter), не сокращая паузу, указанную в Retry-After.
4. Ограничьте число попыток и зафиксируйте окончательную ошибку.
5. Не повторяйте автоматически любой запрос: учитывайте код ответа, семантику метода и защиту операции от дублей.

Для 500, 502, 503 и 504 повтор обычно допустим только для идемпотентной операции или при наличии собственного механизма защиты от дублей. Автоматический повтор POST без такой защиты способен создать дубли.

Коды ответа: что проверять

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

Эталонный шаблон интеграции

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      ...options.headers
    }
  });

  const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
  const body = contentType.includes("json")
    ? await response.json()
    : await response.text();

  if (!response.ok) {
    const error = new Error(`API request failed: ${response.status}`);
    error.status = response.status;
    error.retryAfter = response.headers.get("retry-after");
    error.body = body;
    throw error;
  }

  return body;
}

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

Быстрая проверка интеграции

Как убедиться, что интеграция работает

Минимальная проверка должна завершаться наблюдаемым результатом:

1. Выполните безопасный запрос на чтение или тестовую операцию из документации API.
2. Убедитесь, что получен ожидаемый код ответа.
3. Проверьте обязательные поля и типы значений в теле.
4. Для операции записи повторно запросите созданный или изменённый ресурс.
5. Проверьте отрицательный сценарий: неверные данные должны привести к ожидаемой ошибке, а не к молчаливому успеху.

Для встроенного MCP-сервера n8n нужно включить MCP на уровне экземпляра и отдельно открыть нужные рабочие процессы. Это отличается от узла MCP Server Trigger, который настраивается внутри одного workflow. Для открытия рабочего процесса должны выполняться условия n8n: в частности, он должен быть опубликован и содержать узел-триггер типа webhook, form, schedule или chat. Клиент не получает полный доступ ко всем рабочим процессам автоматически: возможности зависят от выданных разрешений и версии n8n. Актуальные условия описаны в документации n8n MCP server.

Следующий шаг

Webhook простыми словами: как система узнаёт, что что-то произошло

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov