Ваш конспект

API: Связь вашего SaaS с внешним миром

Ключевые тезисы:

• API (Application Programming Interface) — это интерфейс для взаимодействия между программами.
• Любой SaaS взаимодействует с внешними сервисами (платежи, уведомления, мобильные приложения) через API.
• Для создания собственного API достаточно двух HTTP-методов: GET и POST.
• Защита API осуществляется с помощью API-ключей, передаваемых в заголовках запроса.
• Интеграция с внешними сервисами (например, Telegram) организуется через провайдеры — специальные прослойки.

Что такое API? Простая аналогия

Представьте ресторан:

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

Одна программа просит другую: "Дай список пользователей" или "Создай запись". Вторая выполняет и возвращает результат. При этом первой программе не нужно знать, как всё устроено внутри второй.

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

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

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

1. URL (Адрес)
   Указывает, к какому приложению и ресурсу обращаемся (например, /api/users).

2. Метод (HTTP Method)
   Определяет действие. Достаточно двух:

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

3. Заголовки (Headers)
   Служебная информация о запросе:

   • Content-Type: application/json — данные в формате JSON.
   • X-API-Key: ваш_ключ — ключ для авторизации.

4. Тело запроса (Body)
   Есть только у POST. Содержит сами данные для создания/изменения в формате JSON.

   {
     "name": "John",
     "email": "john@example.com",
     "role": "user"
   }
   

Из чего состоит API-ответ?

1. Код статуса (Status Code) — число, указывающее на результат:

   • 200 — Всё хорошо.
   • 201 — Запись создана.
   • 401 — Нет авторизации.
   • 404 — Не найдено.
   • 429 — Лимит запросов исчерпан.
   • 500 — Ошибка сервера.

2. Тело ответа (Body) — данные в формате JSON или текст ошибки.

Защита API: API-ключи

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

Как работает: Сервер проверяет ключ через специальный фильтр. Если ключ неверный, запрос не доходит до основной логики приложения, а сразу возвращает ошибку 401 Unauthorized.

Практика: API в реальном проекте (OneShot)

В модуле users уже есть API-контекст. Вот что он умеет:

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

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

Интеграция с внешним сервисом: Telegram-уведомления

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

Решение через провайдеры:

1. Провайдер — это прослойка между вашим приложением и внешним сервисом. Приложение говорит "отправь уведомление", не зная, как именно.
2. В OneShot уже есть TelegramProvider. Внутри он делает обычный HTTP-запрос к API Telegram-бота.
3. В контроллере создания пользователя, после успешного сохранения, вызываем метод провайдера: TelegramProvider.send("Зарегистрирован новый пользователь: {имя}, {email}").

Настройка:

1. Создать бота в Telegram через @BotFather и получить токен.
2. Получить chat_id администратора, отправив боту сообщение и вызвав getUpdates.
3. Вписать токен и chat_id в настройки приложения.

Преимущество провайдеров: Чтобы заменить Telegram на Slack, нужно изменить только код провайдера, не затрагивая основную бизнес-логику API.

Итоги

• API — это "разговор" между программами по стандартным HTTP-правилам.
• Для своего SaaS достаточно методов GET и POST.
• Свой API вы создаёте, чтобы предоставлять данные другим сервисам (например, мобильному приложению). Защищаете его API-ключами.
• Чужие сервисы подключаете через провайдеры, чтобы использовать их возможности (платежи, уведомления, AI-модели) в своём приложении.