ecentic API 版本控制。
版本号位于路径中。固定版本的集成会持续获得其开发时对应的契约,且不会在没有预警的情况下失效。
URL 路径版本控制 · 180 天通知期 · Deprecation 和 Sunset 响应头
01
版本如何运作
一个数字,位于路径中,仅在出现破坏性变更时才会改变。
当前版本为 v1,服务路径为 /api/v1。每个响应还会在 API-Version 响应头中回显版本,因此跟随重定向或链接的客户端可以确认自己实际连接的是哪个版本。
添加到同一版本
向后兼容的新增变更会在同一版本内发布:新端点、新的可选请求字段,以及现有响应中的新增字段。请将未知响应字段视为前向兼容,而不是错误。
启用新的版本路径
删除字段、重命名字段、收窄类型或改变现有值含义的变更都属于破坏性变更,会作为新版本路径与旧版本并存发布——绝不会原地替换。
弃用与 Sunset
两个标准响应头,以及足够长的处理窗口。
选择一个响应头,查看它向客户端传达的信息。
已宣布弃用
版本已弃用
已弃用版本的每个响应都会携带此响应头。它使用 RFC 9745 宣布版本弃用。
已宣布移除日期
已确定移除日期
确定移除日期后,响应也会携带此响应头。RFC 8594 定义了该版本停止响应的日期。
已关联替代版本
已标明替代版本
在移除日期之外,带有 rel="successor-version" 的 Link 会将客户端指向替代版本。
示例响应头值,并非停用公告。
03
哪些内容不做版本控制
发现文档改为跟随各自协议的版本。
.well-known 发现文档按其实现的协议进行版本控制,而不是按 ecentic API 版本——UCP profile 带有 UCP 版本,MCP server card 带有协议版本,等等。始终以文档内部的版本信息为准;根据 ecentic API 版本推断并不正确。
- ecentic API 合约
- /api/v1
- API-Version: 1
- 发现协议合约
- .well-known
- 读取文档中的版本号