版本控制
使用两个部分版本控制方案：{主要版本}。{次要版本}，API释放是版本的。
我们广泛关注语义版本化版本配置API时的原则。发生倒退不兼容的更改时，主要版本号递增。API中使用的URL通过使用以下模式（相对于基本URL）合并主要版本，反映了这一点：
/ api / v {主要版本号} / {特定于操作组件}
发生后退更改时较小版本编号递增。这些不需要单独的URL。
以下更改被视为倒退不兼容：
- 删除先前支持的HTTP资源
- HTTP资源不再响应先前支持先前支持的HTTP动词
- 输入XML或JSON文档中的一个新的强制属性或元素（这可能是一个完全新的强制属性/元素，或现在是必需的先前可选属性/元素）
- 以前始终始终存在于输出XML或JSON文档中的属性/元素，现在是可选或不存在的
以下更改被视为兼容：
- 添加新的HTTP资源
- 支持现有HTTP资源的其他动词
- 输入XML / JSON文档中的新可选属性或元素
- 以前的强制属性或输入XML / JSON文档中的元素是可选的
- 输出XML / JSON文档中引入的新属性或元素
由于这些列表表示，我们的API产生和消耗的XML / JSON文档不是基于严格的架构。因此，客户端实现应该是灵活的，并且能够支持（例如通过忽略）在本文档中指定的XML / JSON中的新元素和属性。
我们预计在任何给定时间至少支持API（包括当前一）的最近两个主要版本。