Лучшие правила работы с чужим API
Чужой API рано или поздно подведёт: изменится, откажет, ответит не тем, что ожидалось. Шесть правил, которые превращают интеграцию из источника трёхчасовых инцидентов в скучную, предсказуемую часть системы.
Главная установка
Чужой сервис — это не часть вашей системы, а внешний мир, которым вы не управляете. Он может быть недоступен, может ответить медленно, может тихо поменять формат ответа. Код, написанный в расчёте на идеальный сценарий, ломается первым же плохим днём у поставщика.
Топ 6 правил
Ключи и секреты — только в переменных окружения
базовое правило, о котором всё равно забывают
Ключ доступа, попавший в код и отправленный в репозиторий, нужно считать скомпрометированным навсегда, даже если коммит потом удалили — история версий хранит его. Переменные окружения решают вопрос раз и навсегда: ключ хранится вне кода и никогда не попадает в систему контроля версий.
Что сделать дополнительно. Добавить файл с настройками в список исключений с первого дня проекта, а не когда ключ уже утёк.
- Полностью убирает риск утечки через репозиторий
- Разные ключи для разработки и продакшена без правки кода
- Стандартный подход, который знает любой разработчик в команде
- Требует дисциплины с первого коммита
- Утёкший однажды ключ всё равно нужно менять — не удалить из истории
всегда · оценка 9,6
Повторы с нарастающей паузой
спасает от временных сбоев без вашего участия
Сервис может не ответить на один запрос из тысячи — сеть, перегрузка, обслуживание на стороне поставщика. Простой повтор с увеличивающейся паузой между попытками решает большинство таких случаев автоматически.
Как правильно. Не долбить сервис мгновенными повторами — это только усугубляет перегрузку. Пауза должна расти с каждой попыткой: секунда, потом две, потом четыре, и ограничение на общее число попыток.
Чего не повторять. Ошибки, связанные с неверными данными запроса, повторами не лечатся — сервис ответит той же ошибкой сколько угодно раз. Повторять стоит только временные сбои.
- Автоматически переживает временные сбои
- Не требует вмешательства человека каждый раз
- Стандартный, хорошо изученный паттерн
- Требует различать временные и постоянные ошибки
- Неправильная реализация может усугубить перегрузку сервиса
всегда · оценка 9,3
Уважать ограничения частоты запросов
игнорировать их — значит получить временную блокировку
Почти у каждого API есть лимит на число запросов в единицу времени. Превышение обычно означает временный отказ в обслуживании, иногда — для всей вашей учётной записи, а не только для превысившего лимит участка кода.
Что сделать заранее. Изучить документацию по лимитам до того, как начали интеграцию, и заложить очередь запросов с нужной скоростью прямо в код, а не полагаться на то, что «обычно хватает».
- Предотвращает временные блокировки заранее
- Делает нагрузку на внешний сервис предсказуемой
- Экономит время на отладке загадочных отказов
- Требует изучить документацию заранее, а не по факту сбоя
- Может замедлить обработку больших пачек данных
всегда · оценка 9,1
Версионировать интеграцию
чужой сервис меняется без предупреждения вам лично
Поставщик API может выпустить новую версию, а старую в какой-то момент отключить. Явное указание версии в запросах — единственный способ не сломаться неожиданно в день, когда изменится формат по умолчанию.
Практика. Проверять раздел с изменениями документации поставщика хотя бы раз в несколько месяцев, а не узнавать о смене формата по упавшему продакшену.
- Защищает от неожиданных изменений в один день
- Даёт контроль над моментом перехода на новую версию
- Делает поведение системы предсказуемым
- Не все API поддерживают явное версионирование
- Требует следить за анонсами поставщика
всегда · оценка 8,9
Что делать при полной недоступности сервиса
решение продумывается заранее, а не в момент паники
Внешний сервис может лечь на часы. Вопрос не в том, случится ли это, а в том, что должна делать ваша система в этот момент — и ответ нужно знать заранее, а не изобретать во время инцидента.
Варианты ответа, которые стоит рассмотреть. Показать пользователю понятное сообщение вместо технической ошибки, поставить операцию в очередь на потом, откатиться на кэшированные данные, если это применимо к задаче. Худший вариант — просто уронить всю систему из-за одной внешней зависимости.
- Один упавший сервис не кладёт всю систему
- Пользователь видит понятное сообщение, а не ошибку
- Решение принимается спокойно, а не в панике во время инцидента
- Требует продумать сценарий заранее
- Не для каждой операции есть разумная альтернатива
закладывается заранее · оценка 9,0
Логировать запросы и ответы для отладки
когда что-то пошло не так, это единственная зацепка
Без записи о том, что именно было отправлено и что получено в ответ, разбор инцидента превращается в гадание. С логом — это пять минут чтения, чтобы понять причину.
Что важно не забыть. Не записывать в лог ключи доступа, пароли и персональные данные пользователей — логи читают и хранят дольше, чем принято думать. Подробнее об этом — в разборе способов защитить свои данные.
- Резко ускоряет разбор инцидентов
- Показывает реальную, а не предполагаемую причину сбоя
- Помогает заметить проблему до жалоб пользователей
- Легко случайно записать в лог чувствительные данные
- Логи нужно где-то хранить и периодически чистить
всегда · оценка 8,8
Сравнение по главному
| Правило | От чего защищает | Когда внедрять |
|---|---|---|
| Ключи в переменных окружения | утечки доступа | с первого дня |
| Повторы с паузой | временных сбоев | сразу |
| Лимиты частоты | блокировки аккаунта | до запуска |
| Версионирование | неожиданных изменений | сразу |
| План на недоступность | падения всей системы | до продакшена |
| Логирование | долгого разбора инцидентов | сразу |
Минимальный набор перед первым запуском
Обязательно. Ключи в переменных окружения, повторы с нарастающей паузой на временные ошибки, понятное сообщение пользователю при недоступности сервиса.
Сразу после. Изучить и соблюдать лимиты частоты запросов, включить логирование без чувствительных данных.
Можно чуть позже, но не забыть. Явное версионирование интеграции и регулярная проверка изменений в документации поставщика.
Частые вопросы
Сколько раз повторять запрос при ошибке?
Универсального числа нет, но три-четыре попытки с растущей паузой — разумный ориентир для большинства случаев. Больше — и пользователь долго ждёт ответа впустую, меньше — и вы теряете шанс пережить кратковременный сбой. Важнее не число, а то, что паузы растут, а не остаются одинаковыми.
Что делать, если у API вообще нет документации по лимитам?
Начинайте с заведомо низкой скорости запросов и постепенно увеличивайте, наблюдая за ответами сервиса. Ответ с кодом, означающим превышение лимита, подскажет границу опытным путём. Это медленнее, чем чтение документации, но безопаснее, чем предполагать лимит наугад.
Нужно ли всё это для маленького личного проекта?
В сокращённом виде — да, особенно хранение ключей отдельно от кода: это правило одинаково важно и для личного проекта, и для промышленной системы. Остальные пункты можно упрощать пропорционально масштабу — но полностью игнорировать их означает получить сюрприз в самый неподходящий момент.
Как быстро понять, что проблема на стороне внешнего сервиса, а не в вашем коде?
Если логи запросов и ответов уже настроены — обычно за пару минут: видно код ответа и текст ошибки от самого сервиса. У крупных поставщиков часто есть отдельная страница со статусом их систем — полезно проверить её в первую очередь при массовых сбоях.
Итог
Два правила закрывают большую часть реальных проблем: ключи в переменных окружения и повторы с нарастающей паузой на временные сбои. Оба внедряются за час и работают годами без вашего участия.
А план действий при полной недоступности сервиса продумайте заранее, спокойно — а не во время реального инцидента, когда решения принимаются хуже и быстрее, чем хотелось бы.
Комментарии
0Будьте первым, кто ответит автору.