Версионирование Public API в DataLens On-premises
По мере развития Public API в DataLens могут меняться набор и аргументы методов, а также схемы объектов, например дашбордов, чартов, датасетов.
Изменения бывают совместимыми и несовместимыми:
- совместимые — добавление новых полей;
- несовместимые — удаление или переименование полей, изменение структуры схемы, удаление методов.
При несовместимых изменениях создается новая версия Public API: каждое несовместимое изменение приводит к увеличению номера версии API на единицу. При этом, если несовместимые изменения происходят одновременно в нескольких методах или схемах объектов, версия API также увеличивается только на единицу.
Номер версии передается в заголовке запроса X-DL-API-Version. Чтобы указать самую новую версию, актуальную на текущий момент, передайте в заголовке latest.
Предыдущая версия Public API поддерживается в течение некоторого времени после выхода новой версии, чтобы пользователи успели мигрировать на новую версию.
Интерфейс DataLens работает только с последней версией схем, поэтому при редактировании объектов в интерфейсе, они будут автоматически сохранены под последней версией. Таким образом, попытка работы с таким объектом через Public API старой версии вызовет ошибку.
Примечание
Регулярно обновляйте Public API для корректной работы.
Пример совместимого изменения
В метод создания отчета добавили поле для передачи описания:
Было:
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}
Стало:
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config, description}
Если отчет был создан до появления нового поля в Public API, то он будет сконвертирован, и новому полю будет присвоено значение по умолчанию.
Пример несовместимого изменения
В методе создания отчета убрали аргумент key и добавили вместо него workbookId.
Было:
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}
Стало:
X-DL-API-Version: 2
POST http://<хост_on-premises>/rpc/createReport {workbookId, config}
Старое поведение метода можно использовать, пока поддерживается предыдущая версия API. Для этого укажите в заголовке нужную версию:
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}