Версии API и вывод из эксплуатации
Как Hubris версионирует API, как предупреждает об отключении устаревших эндпоинтов и полей (заголовки Deprecation и Sunset) и за сколько дней.
Интеграцию с Hubris можно строить в расчёте на то, что она не сломается без предупреждения. Ниже — правила, по которым мы меняем API.
Версия в адресе
Версия API — часть адреса: https://api.hubris.pw/v1/.... Внутри /v1 мы только добавляем: новые эндпоинты, новые необязательные параметры запроса, новые поля ответа. Клиент должен спокойно пропускать незнакомые поля в ответе — это единственное, чего мы от него ждём.
Несовместимое изменение — удаление эндпоинта или поля, смена типа поля, новый обязательный параметр, другой смысл кода ошибки — выходит только в новой версии, /v2. Старая версия после этого продолжает работать по правилам вывода из эксплуатации ниже.
Как мы предупреждаем об отключении
Эндпоинт, поле или версию API мы отключаем не раньше чем через 90 дней после объявления. В день объявления:
- Ответы устаревшего эндпоинта получают заголовки:
- В журнале изменений появляется запись: что устаревает, чем заменить, дата отключения.
- Владельцы аккаунтов, чьи ключи обращались к устаревшему эндпоинту за последние 30 дней, получают письмо.
До даты из Sunset эндпоинт работает как раньше. Проверить, не пользуется ли ваш код чем-то устаревшим, можно по заголовку Deprecation в ответах.
Что сейчас устарело
Отключаемых эндпоинтов нет. Три поля оставлены для совместимости и помечены в справочнике как устаревшие; дата их отключения не назначена:
| Поле | Где | Замена |
|---|---|---|
data[].modalities | GET /v1/models | output_modalities |
daily_limit_kopecks | Management API, GET /v1/key | limit_kopecks с limit_period: "day" |
spent_24h_kopecks | Management API | spent_period_kopecks |
Когда дата будет назначена, об этом предупредим по правилам выше — не меньше чем за 90 дней.
Бета
Метка бета у /v1/responses относится только к составу блоков ответа в output[]: туда добавляются новые типы по мере того, как их вводят провайдеры моделей. Это расширение, а не несовместимое изменение, поэтому правила выше на него не распространяются. Авторизация, тарификация и потоковая передача у /v1/responses стабильны.
Обновлено: