2026-08-22 是当前(也是创始)版本。当 API 需要破坏性变更(字段改名、响应结构调整)时,变更以一个新日期发布;所有旧版本的行为原封不动。纯新增的变化——新端点、新的可选字段——对所有版本同时生效,不产生新日期。
你永远不必追着 API 跑。今天写好的集成会一直收到今天的结构,直到你决定升级——这正是这套模型的全部意义。
密钥钉住版本
每把 API 密钥都钉在它被创建时的最新版本上。不带版本头的请求,永远按密钥钉住的版本应答。控制台的 API 密钥页面在「API 版本」列展示每把钥匙钉住的版本。按请求覆盖
发送Orriven-Version 头,可以让单个请求按另一个版本应答——这是在正式切换前试用新版本的方式:
400 并列出现存版本。版本不能捏造——只有已发布的日期有效。
每个响应都自报版本
无论版本由什么决定——你的请求头还是密钥的钉住值——响应都会回显它:升级姿势
1
读变更日志
每个新版本的条目(见下)都从调用方视角写清楚到底改了什么。
2
用请求头试跑
让预发环境的集成带上
Orriven-Version 指向新日期——密钥的钉住值不受影响,生产流量继续用旧结构。3
挪动钉住值
生成一把新密钥(自动钉在最新版本),把集成切换过去,再吊销旧密钥——与任何凭证轮换一样零停机。
变更日志
相关页面
API 密钥
密钥钉住的版本在哪里看。
端点参考
当前版本的结构,逐端点列明。