---
metadata:
  - name: generator
    content: Diplodoc Platform v5.63.0
alternate:
  - ru/operations/api-versioning
  - href: ru/operations/api-versioning.md
    type: text/markdown
    title: Markdown version
csp:
  - script-src:
      - https://mc.yandex.ru
    img-src:
      - https://mc.yandex.ru
    connect-src:
      - https://mc.yandex.ru
      - wss://mc.yandex.ru
    child-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-ancestors:
      - 'blob:'
      - https://mc.yandex.ru
canonical: ru/operations/api-versioning.html
title: Версионирование Public API в DataLens On-premises
description: >-
  Версионирование Public API в DataLens On-premises поддерживает совместимость
  методов и схем объектов в API с методами и схемами объектов в интерфейсе.
vcsPath: ru/operations/api-versioning.md
---
# Версионирование Public API в DataLens On-premises

По мере развития Public API в DataLens могут меняться набор и аргументы методов, а также схемы объектов, например дашбордов, чартов, датасетов.

Изменения бывают совместимыми и несовместимыми:

* совместимые — добавление новых полей;
* несовместимые — удаление или переименование полей, изменение структуры схемы, удаление методов.

При несовместимых изменениях создается новая [версия Public API](../release-notes/api-changelog.md): каждое несовместимое изменение приводит к увеличению номера версии API на единицу. При этом, если несовместимые изменения происходят одновременно в нескольких методах или схемах объектов, версия API также увеличивается только на единицу.

Номер версии передается в заголовке запроса `X-DL-API-Version`. Чтобы указать самую новую версию, актуальную на текущий момент, передайте в заголовке `latest`.

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

Интерфейс DataLens работает только с последней версией схем, поэтому при редактировании объектов в интерфейсе, они будут автоматически сохранены под последней версией. Таким образом, попытка работы с таким объектом через Public API старой версии вызовет ошибку.

{% note info %}

Регулярно обновляйте Public API для корректной работы.

{% endnote %}

## Пример совместимого изменения {#non-breaking-change}

В метод создания отчета добавили поле для передачи описания:

Было:

```bash
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}
```

Стало:

```bash
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config, description}
```

Если отчет был создан до появления нового поля в Public API, то он будет сконвертирован, и новому полю будет присвоено значение по умолчанию.

## Пример несовместимого изменения {#breaking-change}

В методе создания отчета убрали аргумент `key` и добавили вместо него `workbookId`.

Было:

```bash
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}
```

Стало:

```bash
X-DL-API-Version: 2
POST http://<хост_on-premises>/rpc/createReport {workbookId, config}
```

Старое поведение метода можно использовать, пока поддерживается предыдущая версия API. Для этого укажите в заголовке нужную версию:

```bash
X-DL-API-Version: 1
POST http://<хост_on-premises>/rpc/createReport {key, config}
```