Версия API
Как узнать версию сервера, как версионируются REST, gateway и вебхуки и что считается совместимым изменением.
GET /api/version
Публичный маршрут без авторизации: версия сборки сервера и сведения о лицензии.
curl -s https://app.example.com/api/versionimport requests
print(requests.get("https://app.example.com/api/version").json()["version"])JSON
{
"version": "3.3.0",
"commit": "75c4474",
"license": "BUSL-1.1",
"commercialLicense": "…",
"attribution": "…",
"url": "…",
"product": "Calab",
"planContact": "…"
}| Поле | Что это |
|---|---|
version | версия релиза сервера; dev — локальная сборка |
commit | короткий git-коммит сборки; unknown, если не проставлен |
license | SPDX-идентификатор лицензии |
commercialLicense | где получить коммерческую лицензию |
attribution · url | текст и ссылка атрибуции, которую показывают клиенты |
product | название продукта для людей |
planContact | куда обращаться за платным тарифом |
Сверяйте version с журналом изменений API, чтобы понять, есть ли на сервере нужная вам возможность.
Как версионируется API
| Интерфейс | Версия | Правило |
|---|---|---|
REST /api/… | без версии в пути | только расширяется: новые маршруты, поля и значения перечислений; существующие не меняют смысл |
| Gateway | ?v=1 в адресе | новые события и поля добавляются без смены версии; несовместимое изменение — новая версия протокола |
| Вебхук бота | — | тело — BotWebhookUpdate, растёт как события gateway |
| Вебхук доски | заголовок X-Calab-Webhook-Version: 1, поле version | поля только добавляются |
| OAuth / OIDC | discovery-документ пространства | возможности провайдера перечислены в /.well-known/openid-configuration |
Как писать совместимый клиент
- Пропускайте незнакомые поля ответов и событий — они появляются без предупреждения.
- Обрабатывайте незнакомые значения перечислений как «другое», а не как ошибку.
- Не полагайтесь на порядок полей в JSON и на текст
messageв ошибках. - Передавайте только известные вам поля запроса: сервер игнорирует неизвестные, поэтому опечатка в имени поля не вызовет ошибку — проверяйте ответ.
- Числа
uint64(размеры файлов,seq) приходят строками — не теряйте точность.