API Client

Гайд по интеграции с внешними API.

Чек-лист

Подготовка

• Изучи документацию API (эндпоинты, лимиты, аутентификация)
• Получи ключи/токены, сохрани в env (не коммить)
• Определи модели данных (типы/схемы для ответов)

HTTP-клиент

• Единый клиент с базовым URL и таймаутами
• Повторные попытки (retry) с экспоненциальной задержкой при 429/5xx
• Rate-limiting: соблюдай лимиты, добавляй бэк-офф
• Логирование запросов (без секретов/паролей в логах)

Авторизация

• OAuth 2.0: flow + refresh-токен, перевыпуск по истечении
• API-ключ: заголовок Authorization/X-API-Key, не в URL
• Храни секреты в vault/env, ротация ключей

Обработка ошибок

• Различай 4xx (клиентская) и 5xx (серверная)
• Понятные сообщения, ретраи только для идемпотентных
• Таймауты и circuit-breaker для нестабильных сервисов

Надёжность

• Кэширование ответов при возможности
• Обработка webhook-ов (проверка подписи, идемпотентность)
• Graceful degradation при недоступности API

Правила

1. Секреты — только из env/secret-manager, нигде в коде/логах.
2. Уважай rate-limit: ретраи с бэк-оффом, не молоти сервер.
3. Моделируй ответы явно (типы), не работай с «сырым» JSON.
4. Пиши тонкий слой-обёртку над API для заменяемости.