可维护性
API需要保持向后兼容性
本条规则是MUST类型的基本规则，可保障API的可维护性。
- 现网API版本一般保留3个版本或以下，如果超过3个版本会增加API本身的维护量，建议对旧版本API进行下线处理。
- 服务端API改动必须保证所有的服务消费者不被破坏。API是服务端和客户端的契约，不能单方面破坏契约。通过如下的方式来保证向后的兼容性：
- 遵循兼容扩展标准。
- 忽略请求/响应中的未知字段。
- 只添加可选字段，不能添加必选字段。
- 不能更改字段的含义。
- 当资源URL发生变化的时候，支持重定向。
- 服务端提供新版本API的同时，需要对老版本API提供支持。
例如：应用A更新API查询虚拟机列表，增加多个新的查询条件。在API发布之后，之前订阅该API的应用不能因为增加了新的查询条件而造成查询虚拟机列表失败。
API请求HTTP动词使用标准化且满足幂等性
本条规则是Should类型的扩展规则，可提升API的可维护性。
HTTP方法的需要符合幂等性的约束，幂等性的约束是指一次和多次请求某一个资源应该具有同样的副作用，单个资源操作，资源的标准CRUD操作对应的HTTP动词如表1所示。
方法 |
描述 |
幂等性 |
|---|---|---|
POST |
适用于新建资源场景，以及CRUD无法表达的操作场景（Non-CRUD）。 |
否 |
GET |
用于获取资源的场景，必须具备安全性。 |
是 |
PUT |
如果操作的URL为一个新资源，则创建该资源。如果URL为一个已存在的资源，则替换该资源，传入的消息体需包含被替换资源的完整信息。如果传递的信息不完整，在服务实现端需提供对应信息的默认值。 |
是 |
DELETE |
用于删除资源的场景。 |
是 |
HEAD |
返回资源的元信息比如：ETag和Last-Modified之类的信息。 |
是 |
PATCH |
用于部分更新资源的场景，如果使用PUT操作所需输入的整体资源信息内容大小与PATCH操作无太大差异，优先使用PUT操作，不推荐使用PATCH操作。 |
是 |
OPTIONS |
获取当前资源支持哪些方法的信息。 |
是 |
例如：使用正确的HTTP动词。
- “查询虚拟机列表”：GET /servers
- “创建VPC网络”：POST /vpc
- “删除虚拟机标签”：DELETE /server/tag
- “创建/更新数据库实例元数据”：PUT /instance/metadata
API建议明确标识出版本号
本条规则是Should类型的扩展规则，可提升API的可维护性。
每个API建议带上版本号，保证API的版本显性化，容易被API调用者所识别。版本号建议放置在URI中，用于显性标识所请求的API版本。
服务所提供的API版本定义统一规范成“vX”，这里X是一个正整数如：v1，v2等，要在API版本文档中明确在接口中说明清楚哪个版本号是目前服务主推的版本，哪些版本是支持但已经不推荐的版本，方便API调用者通过该接口快速了解与跟进服务API的变化。如果无法在URI中进行API版本标识，则可在HTTP Header中进行API版本标识。
例如：应用A提供API查询虚拟机列表GET /servers，可在URI上进行版本标识，如GET /v1/servers，GET /v2/servers，同时提供相关的API文档说明不同版本之间的区别。
