Версии и изменения

Версия в пути

Версия API указывается в пути: https://api.lexaai.ru/v1/…. Совместимые изменения выходят в текущей версии, несовместимые – в новой версии пути (/v2). Версию манифеста возвращает поле version ответа GET /v1/tools.

Несовместимые изменения

Выходят только в новой версии пути:

• удаление или переименование эндпоинта, поля запроса или поля ответа;
• изменение типа поля или его смысла;
• новое обязательное поле запроса;
• изменение значения по умолчанию, которое меняет результат запроса;
• изменение способа передачи ключа;
• другой код ответа для прежней ситуации.

Совместимые изменения

Могут выходить в текущей версии без предупреждения:

• новые эндпоинты и новые необязательные поля запроса;
• новые поля ответа;
• новые значения перечислимых полей ответа, например причин деградации или этапов конвейера;
• уточнение текстов detail, gaps, degradation.message и описаний в манифесте;
• изменение состава корпуса, ранжирования и качества поиска;
• изменение ограничения частоты планов по правилам, описанным в разделе Авторизация и лимиты.

Требования к клиенту

• Игнорировать неизвестные поля ответа.
• Обрабатывать неизвестное значение перечислимого поля как общий случай: например, неизвестную причину деградации – как отказ канала.
• Не строить логику на текстах сообщений и порядке полей.
• Брать текст дисклеймера из поля disclaimer ответа, а не из копии в коде клиента.

Объявление и прекращение версий

Несовместимое изменение объявляется в журнале изменений до выпуска новой версии пути. Срок, в течение которого /v1 и /v2 работают параллельно, указывается в журнале при выпуске /v2.

Сервис работает в режиме бета-тестирования. Если для устранения ошибки или угрозы безопасности потребуется несовместимое изменение в /v1, оно будет отмечено в журнале изменений с датой.

Журнал изменений