> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Версионирование и совместимость API

> Обработка обратно совместимых изменений API, непрозрачных идентификаторов, новых типов событий и версий в URI.

YCloud использует версии в URI для изменений API, нарушающих обратную совместимость. Текущий базовый URL API:
`https://api.ycloud.com/v2`.

## Обратно совместимые изменения

Ваша интеграция должна поддерживать следующие изменения в рамках одной и той же версии API:

* Новые ресурсы API.
* Новые необязательные параметры запроса для существующих операций.
* Новые свойства в ответе или изменение порядка свойств в ответе.
* Изменения длины или формата непрозрачных строк, включая идентификаторы объектов,
  сообщения об ошибках и другие понятные человеку строки.
* Новые значения перечислений (enum), включая новые типы событий Webhook.

Игнорируйте неиспользуемые свойства ответа. Обрабатывайте незнакомые типы событий,
не допуская сбоя всего обработчика Webhook. Для управления логикой используйте
задокументированные коды ошибок вместо сопоставления понятного человеку текста ошибки.

## Хранение непрозрачных идентификаторов

Относитесь к идентификаторам объектов как к непрозрачным строкам, чувствительным к регистру. Не делайте предположений о значении,
основываясь на длине ID или префиксе, таком как `evt_`; префиксы могут добавляться или удаляться.
Созданные YCloud идентификаторы объектов не превышают 255 символов. Предусмотрите эту полную
длину в вашем хранилище данных.

Например, в столбце MySQL можно использовать `VARCHAR(255) COLLATE utf8_bin`, чтобы сохранить
чувствительность к регистру при сравнении.

## Критические изменения (Breaking changes)

Изменение, нарушающее обратную совместимость, использует другую версию в URI запроса. Например:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.ycloud.com/v1/balance
https://api.ycloud.com/v2/balance
```

Используйте версию, задокументированную для вашей интеграции. Не изменяйте сегмент версии,
не проверив контракты запросов, ответов и Webhook.

Ознакомьтесь с [журналом изменений API](/ru/api-reference/getting-started/changelog) для просмотра истории изменений.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.