版本控制

Partner API 在 URL 中标明版本。当前版本为：

https://partner-api.performancehub.co/partner/v1/

变更政策

Performance Hub 力求尽可能进行增量式、向后兼容的变更。

向后兼容变更的示例：

• 在请求中添加新的可选字段。
• 在响应中添加新字段。
• 添加新端点。
• 在客户端应能处理未知值的情况下添加新的枚举值。
• 在不改变状态码约定的情况下改进验证消息。

access_time_windows 和 access_time_windows_revision 是增量添加的会员请求字段。省略这些字段的现有客户端会保持已存储的 Access Time Window 快照不变。此省略规则保留了部分更新插入的兼容性；省略并不等同于发送空数组。

破坏性变更的示例：

• 移除或重命名字段。
• 更改字段的类型。
• 将可选的请求字段改为必填。
• 移除端点。
• 更改现有状态码或特定领域 reason 的含义。

弃用

当需要进行破坏性变更时，Performance Hub 会尽可能避免直接修改现有版本，而是引入新版本或迁移路径，并将变更告知受影响的合作伙伴。

弃用通知可能包括：

• 更新日志条目。
• 与合作伙伴的直接沟通。
• Partner Console 中的说明。
• 文档中的迁移指南。

客户端建议

构建能够容忍增量变更的客户端：

• 忽略您不使用的响应字段。
• 将未知的枚举值视为不受支持，而不是导致崩溃。
• 避免对响应进行严格的相等性检查。
• 记录无法识别的值，以便您有计划地更新集成。

对于带修订号的会员分区（例如 Access Time Windows），请持久保存已提交的修订号和规范化负载，直到获知结果。对已更改的内容重复使用修订号会产生冲突，而重放相同的内容则是幂等的。请参阅 Access Time Windows。

OpenAPI 规范

使用已发布的 OpenAPI 规范生成客户端、验证请求，并跟踪 API 结构随时间的变化。

请参阅 OpenAPI 规范。