Интеграция AI API не готова, когда первый запрос вернул 200. Она готова, когда контракты, права, сбои, повторы и сохранённые результаты ведут себя предсказуемо.
Рассматривайте модель как один компонент контролируемой бизнес-транзакции.
Сначала контракт, потом промпт
Зафиксируйте endpoint, метод, авторизацию, схемы запроса и ответа, коды, timeout, rate limits и версионирование. Определите обязательные поля и владельца каждого ID.
Промпт не является API-контрактом. Проверяйте выход модели по строгой схеме до записи.
Разделите identity, authentication и authorisation
Используйте отдельную service identity и минимальные scopes. Разведите чтение и запись; не выдавайте удаление процессу чтения и обновления.
OWASP относит broken object-level authorisation и broken authentication к главным API-рискам. Сверяйтесь со статьёй о защите данных.
Храните секреты вне контента
Токены должны быть в secret manager или защищённой конфигурации, не в промптах, логах, Trello и коде. Ограничьте выдачу, ротацию и вывод ошибок.
Не передавайте конфиденциальные данные до проверки цели, условий поставщика, региона, retention и прав.
Сделайте записи безопасными и повторяемыми
Используйте idempotency key или transaction ID, если retry может создать дубль. После записи перечитайте ресурс.
Уточните, частичное ли обновление или полная замена. Read-before-write нужен при полном PUT.
- проверять владельца объекта
- отклонять лишние поля
- разделять временные и постоянные ошибки
- ограничивать retry и применять backoff
- хранить before/after важных записей
Валидируйте каждую границу
Проверяйте файлы и URL, выход модели, tool arguments, API response и сохранённую запись. Разрешайте только нужные адреса, чтобы снизить риск SSRF.
Для важных действий применяйте human approval.
Спроектируйте timeout, fallback и reconciliation
Разделите timeout подключения и операции. После timeout удалённая запись могла состояться.
До повторной записи запросите состояние по transaction ID. Периодически сверяйте ожидаемое и фактическое состояние.
Тестируйте систему целиком
Используйте сценарии из предзапусковой проверки: неверная схема, отсутствующее поле, истёкший токен, rate limit, timeout, дубли, частичный ответ и чужой объект.
Приёмка — это правильное состояние бизнеса, а не успешный HTTP-запрос.
Реальная ловушка полного обновления
В одном API PATCH отсутствует, а PUT требует полный объект статьи. Обновление только status могло стереть остальные поля.
Я выполняю GET, сохраняю обязательные поля, меняю одно значение, отправляю полный PUT, снова делаю GET и сравниваю все 21 поле. DELETE исключён полностью, хотя права токена его допускают.
Безопасность здесь дала явная семантика метода и проверка результата, а не код успеха.
Вопросы и ответы
Должен ли AI обращаться к API напрямую?
Лучше через контролируемый tool-layer с валидацией и политиками. Не выдавайте модели общий HTTP-клиент.
Когда повторять запрос?
Только при определённых временных ошибках и с лимитом. Неопределённую запись сначала сверяют.
Что такое idempotency?
Повтор логически одного запроса не создаёт дополнительных эффектов. Нужен стабильный ключ и серверный контроль.
Достаточно ли 200?
Нет. Проверьте сохранённое состояние и итог бизнеса.
Что логировать?
ID запроса, версию контракта, решение политики, вызов, результат, ошибку, retry и before/after без секретов.
Операционный лист контроля
До согласования занесите каждый контроль в таблицу: владелец, доказательство, порог и дата следующей проверки. Фраза «контролировать качество» не исполнима. Правило «операционный владелец каждый понедельник проверяет долю существенных исправлений и ставит процесс на паузу выше согласованного порога» можно проверить.
Свяжите контроль с последствием для бизнеса. Если ошибка схемы может повредить карточку клиента, опишите containment и reconciliation. Если всплеск стоимости объясняется сезонным объёмом, задайте контекст, защищающий от ложной эскалации.
Версионируйте промпты, схемы, политики, инструменты и внешние зависимости. Результат без конфигурации нельзя воспроизвести. У исключений должны быть причина, владелец и срок окончания, иначе временный обход станет невидимой постоянной политикой.
Отрепетируйте человеческий путь. Назначенный владелец должен найти доказательства, остановить или ограничить workflow, включить fallback и объяснить состояние без просьбы к самому AI диагностировать себя.