[Документация Yandex Cloud](../../index.md) > [Yandex DataLens](../index.md) > DataLens Public API > Версионирование

# Версионирование Public API в Yandex DataLens

По мере развития 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 api.datalens.yandex.net/rpc/createReport {key, config}
```

Стало:

```bash
X-DL-API-Version: 1
POST api.datalens.yandex.net/rpc/createReport {key, config, description}
```

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

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

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

Было:

```bash
X-DL-API-Version: 1
POST api.datalens.yandex.net/rpc/createReport {key, config}
```

Стало:

```bash
X-DL-API-Version: 2
POST api.datalens.yandex.net/rpc/createReport {workbookId, config}
```

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

```bash
X-DL-API-Version: 1
POST api.datalens.yandex.net/rpc/createReport {key, config}
```

## Просмотр старой версии в Swagger {#swagger-versions}

В течение переходного периода можно просматривать старую версию API в Swagger. Для этого укажите номер версии в ссылке:

   > `https://api.datalens.tech/<номер_версии>`