API 版本与弃用策略

版本管理

AnyToURL API 使用 API-Version 头进行版本管理。版本 1 是当前稳定面。每个 API 响应都会在 API-Version 响应头中回显所服务的版本，因此客户端可以确认它们正在与预期面通信。

GET /api/config/public
API-Version: 1

省略该头等同于请求版本 1。发布的 OpenAPI 规范 始终描述当前的稳定面。

版本之间的变化

• 破坏性变更 —— 删除或重命名字段、改变响应结构或改变认证要求的变更 —— 以版本 2 在同一路径下发布。版本 1 继续提供旧契约。
• 增量变更 —— 新端点、新可选字段、新响应属性 —— 向后兼容，可以在稳定版本内出现而无需版本升级。

弃用信号

在弃用操作被移除之前，客户端会收到机器可读信号：

1. 受影响操作上的 Deprecation / Sunset 响应头。Sunset 头带有该操作预期停止服务的日期。
2. OpenAPI 规范中的 x-deprecation-policy 以机器可读形式描述策略。

弃用操作在替代版本发布后至少 180 天内保持支持。在此期间，旧操作继续无变化地工作。

Agent 指南

• 显式发送 API-Version: 1 以固定你的集成版本。
• 读取每个响应上的 Sunset 头；如果出现，迁移到替代操作。
• 在采用端点之前，检查 /openapi.json 中的当前 schema。
• 破坏性变更永远不会在没有版本升级和文档化替代方案的情况下发布。

问题

如有任何关于 API 契约的问题，请联系 support@anytourl.com。