Изменения контракта

Что мы обещаем

Публичный контур — это /v1. Внутри одной версии мы:

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

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

Где смотреть, что изменилось

Машинная спека лежит по адресу /openapi.json и собирается из живого кода на каждой сборке — не переписывается руками и не отстаёт. Сравнение двух её версий и есть точный список изменений контракта: ключи в ней отсортированы специально, чтобы дифф читался как перечень правок, а не как перестановка строк.

Версия SDK

agentum-cloud-sdk выпускается автоматически при изменениях клиента; номер версии монотонно растёт. Обновление:

pip install -U agentum-cloud-sdk

Покрытие контракта клиентом проверяется тестом на нашей стороне: маршрут без метода в SDK роняет сборку. Практически это значит, что новая возможность API появляется в клиенте в том же релизе, а не «когда-нибудь».