API 兼容性策略和废弃策略

兼容性策略

与更早版本或非重大更改兼容

添加可能扩展现有 API 资源的资源 URI

此更改通常是安全的。 但是，此更改必须考虑可能生成与此更改冲突的代码的热门客户机框架。 以下示例是可能破坏客户机生成的代码的更改类型，应加以避免。

• 存在 API /v1.0/foo/bar。 代码生成器可能会生成 GetBar 作为客户机方法。 如果引入了新的 API /v1.0/foo/{param}，其中 {param} 是任意字符串，那么代码生成器可能会生成新的客户机方法 GetFoo(String param)。 此更改可能导致客户机上发生重大更改，因为不再会调用 GetBar 中嵌入的逻辑。
• 当前路径 /v1.0/foo/bar 可能导致客户机生成的代码 GetBar 和 GetBarAsync。 新增 API /v1.0/foo/Async 会与此生成的代码冲突。

将 HTTP 方法添加到 API 接口

只要此更改之前的请求有效内容继续存在并以相同方式运作，此更改就是安全的。 可选的一个或多个字段可以添加到现有 API 的请求主体或添加为查询字符串参数。

添加可选的请求头

只要此更改之前的请求继续以相同方式响应，此更改就是安全的。

将允许值添加到现有属性

API 模型使用字符串来表示允许受约束的值列表的属性。 例如，可以记录资源中的 type 以列出资源类型的当前列表。 客户机应当使用通用字符串来表示这些类型，而不是使用明确定义的 enum 类型的严格编组。 接受带有多个可能值的属性的资源可以增强为允许更多值。 这一个或多个新值可以引入对应的新属性和验证规则。 客户机必须确保不通过使用无效 enum 值发出请求并期望出现错误响应等方式来验证不存在的 enum 值。

现有属性值继续支持现有行为。 包含资源类型上的分支逻辑等内容的任何客户机代码都将继续像之前那样运作。

将可选的字段和/或头添加到响应

可选的字段和头随时可以添加到 API 响应。 客户机必须针对此类更改进行调整。

更改 API 响应中的错误消息和资源描述

错误响应中的 messageId 字段被视为不可更改，并应当始终涵盖错误条件或情况的声明列表。 与此消息关联的描述可以更改，而不改变消息对于用户的语义含义。

客户机不得基于 messageDescription 属性构建逻辑。

扩大错误消息标识的作用域

messageId 字段指的是一个或多个错误条件。 随时可以扩展此 messageId 以涵盖更多错误条件。 但是，任何此类扩展都应当符合逻辑，而不能是任意的。 新的错误条件必须与此消息涵盖的现有错误条件密切相关。

对头和错误进行比率限制

比率限制可以在 API 的生命周期内针对 API 端点进行调整，而不需要版本更新。

针对过多请求接收到 HTTP 状态码 429 的客户机必须进行调整。

重大更改

除去或重命名 API 资源端点或 HTTP 方法

此类型的更改会破坏使用该 API 的任何客户机，因此是不允许的，除非存在做出此更改的强烈安全需要。 尽量避免此类更改。

除去或重命名 enum 值

可以添加 enum 的值，而不能将其除去。

更改字段的 type

通常，字段的 type 不能更改。 但是，如果 API 实现能够接受先前 type 并使用先前 type 进行响应，那么此更改被视为与更早版本兼容。

更改现有请求的可视行为

如果某个请求先前导致特定操作或响应，该请求必须继续以此方式运作。 唯一的例外是允许以新错误消息、HTTP 状态码和请求或响应字段形式允许对现有合同进行的扩展。

废弃策略