版本与兼容性

API 只有一个主版本 /v1，并且只增不减。今天编写的集成在新功能推出后仍能继续工作：它依赖的任何内容都不会被重命名、删除或赋予新的含义。

版本号

API 有一个版本号，例如 1.62.0。每次发布时版本号都会变化：

• 新增内容（接口、字段、事件）时，次版本号增加；
• 只更正说明或消息文本、没有其他变化时，修订号增加。

随时可以查看某个地址所提供的版本：

GET /v1/health 也有 version，但它是提供该地址的 Sursa 发行版的版本，而不是 API 的版本。

次版本不能自选：每个请求都由当前版本处理。有了下面的规则，这样做是安全的。

/v1 中可能变化的内容

以下变更可能出现在任何次版本中。编写集成时，请确保它们不会造成破坏：

• 新的接口。
• 新的可选参数和请求字段。不带它们的请求行为不变。
• 响应、对象和事件中的新字段。
• 响应中枚举的新值，例如新的卡片状态或新的事件类型。
• 新的错误码和新的响应头。
• 放宽的限制：更长的最大长度、更宽的取值范围。
• 错误的 message 文本和说明的措辞调整。

代码必须能容忍的情况

• 忽略不认识的字段。响应中的字段比预期多时不要报错，也不要使用会拒绝多余字段的严格结构定义。
• 接受不认识的枚举值。响应中的每个枚举都可能增加值。请把不认识的值当作“其他”，而不是错误。
• 跳过不认识的事件类型，Webhook 和流中都是如此。
• 按 HTTP 状态处理不认识的错误码：参见错误。
• 不要依赖 JSON 对象中字段的顺序，也不要依赖消息的确切文本。

/v1 中永远不变的内容

• 路径、参数、字段或枚举值永远不会被重命名或删除。
• 字段的类型永远不变，字段也不会被赋予新的含义（例如换用新的单位）。
• 今天被接受的请求，以后也不会被拒绝。
• 成功响应的状态码保持不变。
• 错误码的含义保持不变，错误响应中 detail 字段的形式也保持不变。
• 事件类型永远不会被重命名或删除，其 data 只会增加字段。

破坏性变更

如果将来确实需要不兼容的变更，会以新的主版本（例如 /v2）发布，与 /v1 并存。/v1 照常工作，保持不变，两个版本同时运行。

某个路由即将停用时：

1. 它在规范中标记为 deprecated，并在更新日志中列出，注明停用日期。
2. 它的响应带有 Deprecation: true 和 Sunset: <date> 头。
3. 公告后它至少继续工作 180 天。使用它的 API 密钥所属的组织会至少提前 90 天收到书面通知。
4. 停用日期过后，它在之后的 90 天内返回 410，错误码为 api.gone。

请在日志或监控中留意 Deprecation 头：它是您使用的路由即将下线的最早信号。

及时了解变更

本门户的更新日志列出了每次发布新增和弃用的内容。升级自己的集成之前，请对照代码查看自构建时所依据的版本以来的所有条目。