MindSphere API 版本控制¶
每个 MindSphere Web 服务 API 均与一个版本值相关联。MindSphere 中的 API 版本控制是基于语义的版本控制。要识别 API 的特定版本,使用三个版本值:
主要版本¶
主要版本更新表示中断 API 中的更改。API 主要版本是调用服务 API 的 MindSphere Gateway URL 路径的一部分。有关更多信息,请参见 MindSphere Gateway 概念。
如果现有正式 API 功能的行为发生变化,例如使用该功能的客户端无法工作,则将更改视为中断。要使用更新后的版本,需修改客户端。中断更改包括:
- 删除、重命名或移动 API 实体,如:
- 端点
- 与端点关联的 HTTP 方法
- 操作查询参数、文本参数或消息头参数
- 架构属性
- 授权角色
- 改变现有所需功能的使用方式,例如,通过引入新的待满足前提条件
- 更改现有工作流程
- 将可选参数或架构属性更改为强制项
- 对正式的功能或非功能行为做出重要变更
主要版本更新时,会将次要版本和修补程序版本重置为初始值零。例如,如果版本为 v3.1.2 的 API 进行主要更新,则版本值将更改为 v4.0.0。
次要版本¶
次要更新表示在 API 中进行了向后兼容的更改。与 MindSphere 次要更新规则兼容的客户端将继续使用更新后的 API 版本。
如果 API 中加入了可选的新功能,则更改被视为向后兼容。例如,添加上文提及的可选 API 实体以中断更改。如果客户端能接受新的 API 实体(例如,新的可选架构属性或新的错误响应),则认为客户端与 MindSphere 次要更新规则兼容。
次要版本更新会将修补程序版本值重置为零。例如,如果版本为 v3.1.2 的 API 进行了次要更新,则版本值将更改为 v3.2.0。
修补程序版本¶
修补程序版本更新仅涉及 API 规范文档。实际实施保持不变。修补程序更新是对 API 规范中的描述或示例进行的更正或改进。修补程序更新还会修复 API 的规范与实际实施之间的不匹配情况。后者对于想要开发兼容客户端的客户端开发者尤为重要。
Last update: March 22, 2023