API для SaaS сервиса: как организовать взаимодействие между программами

Ключевые цифры

Что такое API и зачем нужен

API — это язык общения программ

API (Application Programming Interface) — интерфейс для взаимодействия между программами. Это не сложный механизм, а просто стандартный способ, по которому одна программа просит другую: «Дай мне данные» или «Создай запись».

Любой SaaS взаимодействует с внешним миром именно через API: получает платежи от Stripe, отправляет уведомления через Telegram, синхронизирует данные с мобильным приложением. И сам предоставляет API для других приложений.

Аналогия с рестораном

Представьте ресторан, и всё станет ясно:

• Меню — это список доступных запросов (эндпоинтов) API
• Официант — сам API интерфейс
• Ваш заказ — это запрос (Request) с параметрами
• Принесённое блюдо — ответ (Response) с данными

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

Пример: Ваш SaaS принимает платежи через API Stripe. Вы отправляете: «Прими $29 с этой карты». Stripe отвечает: «Готово, вот ID транзакции». Внутренняя кухня Stripe вас не касается — вы работаете с интерфейсом.

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

HTTP-запрос — основа всего

Любой API-запрос — это HTTP-запрос (как при открытии страницы в браузере), но данные передаются в формате JSON вместо HTML. Запрос состоит из четырёх компонентов:

1. URL (адрес)

Указывает, к какому ресурсу обращаемся. Например: /api/users — получить список пользователей, /api/users/123 — данные пользователя с ID 123.

2. HTTP-метод

Определяет действие. Для большинства задач достаточно двух:

• GET — получить данные (можно открыть в браузере как обычную ссылку)
• POST — отправить данные, создать или обновить запись

Например: GET /api/users — получить всех пользователей, POST /api/users — создать нового пользователя.

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

Служебная информация о запросе в формате ключ-значение:

• Content-Type: application/json — данные в формате JSON
• X-API-Key: ваш_ключ — ключ для авторизации (защита)
• Authorization: Bearer token — альтернативный способ авторизации

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

Есть только у POST и PUT. Содержит данные в JSON формате. Например, при создании пользователя:

Content:

{

"name": "John",

"email": "john@example.com",

"role": "user"

}

GET-запрос не имеет тела — он только получает, но не отправляет данные.

API-ответ и коды статуса

Что вернул сервер

После запроса сервер всегда возвращает два компонента: код статуса и тело ответа.

Код статуса (Status Code)

Это трёхзначное число, которое показывает результат обработки запроса. Основные коды:

• 200 OK — запрос успешен, вот ваши данные
• 201 Created — запись успешно создана
• 400 Bad Request — неверные параметры в запросе
• 401 Unauthorized — нет авторизации (неверный API-ключ)
• 404 Not Found — ресурс не найден
• 429 Too Many Requests — лимит запросов исчерпан (throttling)
• 500 Internal Server Error — ошибка на сервере

По коду ответа приложение понимает, что произошло, и может действовать соответственно.

Тело ответа (Response Body)

При успехе — JSON данные, при ошибке — текст ошибки. Например, успешный ответ список пользователей:

Content:

[

{ "id": 1, "name": "John", "email": "john@example.com" },

{ "id": 2, "name": "Jane", "email": "jane@example.com" }

]

При ошибке вы получите объект с описанием проблемы и идентификатором запроса для отладки.

Защита API: ключи и авторизация

Почему нужна защита

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

API-ключ как пропуск

Самый простой и распространённый способ защиты — API-ключ, который передаётся в заголовке каждого запроса под именем X-API-Key.

Как это работает:

1. Вы генерируете уникальный ключ для каждого клиента (например, мобильное приложение или интеграция с третьей стороной)
2. Клиент отправляет запрос с этим ключом в заголовке
3. Сервер проверяет ключ через специальный фильтр перед обработкой
4. Если ключ неверный или отсутствует, запрос сразу возвращает ошибку 401 Unauthorized
5. Если ключ верный, запрос обрабатывается обычным порядком

Практика в коде

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

Совет: Никогда не передавайте ключ в URL или в теле запроса — только в заголовках. Заголовки не логируются в браузере и менее видны при перехвате трафика.

Интеграция с внешними сервисами

Провайдеры как переводчики

Ваш SaaS редко работает в одиночку. Нужны платежи (Stripe), уведомления (Telegram, Email), AI модели (OpenAI). Каждый внешний сервис имеет собственный API с разными правилами и форматами.

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

• Приложение говорит: «Отправь уведомление»
• Провайдер знает, как это сделать (Telegram, Slack, Email, SMS)
• Если нужно заменить Telegram на Slack, меняете только провайдер, основная логика не страдает

Пример: Telegram-уведомления

Задача: При создании пользователя через API отправлять уведомление администратору в Telegram.

Решение:

1. Создайте бота в Telegram через @BotFather и получите токен
2. Получите chat_id администратора (отправьте боту сообщение, вызовите getUpdates)
3. Вписать токен и chat_id в настройки приложения
4. В контроллере создания пользователя вызовите метод провайдера: TelegramProvider.send("Зарегистрирован новый пользователь: {имя}, {email}")

Провайдер внутри делает обычный HTTP POST-запрос к API Telegram-бота. Но ваш код об этом не знает и не волнуется.

Преимущество: Чтобы добавить уведомление в Slack, создаёте SlackProvider с той же сигнатурой, и контроллер работает без изменений. Провайдеры — это инверсия зависимостей в действии.

Архитектура SaaS API на практике

Структура реального проекта

В реальном SaaS (например, OneShot) API контроллер обычно имеет такую структуру:

Маршруты (Routes)

Все API эндпоинты объединены в группу с общим префиксом /api и фильтром проверки ключа:

• GET /api/users → получить список всех пользователей
• GET /api/users/{id} → получить пользователя по ID
• POST /api/users → создать нового пользователя
• POST /api/users/{id} → обновить профиль пользователя
• POST /api/users/{id}/delete → удалить пользователя

Контроллер (Controller)

Контроллер API наследует базовые методы и делает одно правило: каждый метод делает одно действие:

1. Принимает параметры из запроса
2. Валидирует данные
3. Обращается к модели для обработки
4. Возвращает JSON с результатом

Безопасность (Middleware)

Все маршруты защищены на уровне группы. Фильтр проверяет API-ключ перед вызовом контроллера. Если ключ неверный, 401 возвращается сразу, без входа в бизнес-логику.

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

Вопросы и ответы

Главное