> ## 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 针对非向后兼容的重大 API 变更使用 URI 版本。当前 API 基础 URL 为
`https://api.ycloud.com/v2`。

## 向后兼容的变更

您的集成必须能够容纳同一 API 版本内的以下变更：

* 新增 API 资源。
* 现有操作中新增的可选请求参数。
* 新增响应属性，或响应属性的顺序发生改变。
* 不透明字符串的长度或格式变更，包括对象 ID、
  错误消息以及其他人类可读字符串。
* 新增枚举值，包括新增 Webhook 事件类型。

忽略未使用的响应属性。妥善处理不熟悉的事件类型，避免导致整个 Webhook 接收端失败。请使用文档中记载的错误代码进行控制流判断，而不是匹配人类可读的错误消息。

## 存储不透明标识符

请将对象 ID 视为不透明且区分大小写的字符串。不要根据 ID 的长度或类似 `evt_` 的前缀来推断含义；前缀可能会被添加或删除。YCloud 生成的对象 ID 不超过 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 变更日志](/zh/api-reference/getting-started/changelog)。


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