易用性

API名称必须易于理解、见名知义

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

• API名称要简洁、易于理解、见名知义，建议按照“动词+名词”格式。
• 在生产环境的API不能包含“test、uat、sit、beta”等字样，API名称只支持中文、字母、数字以及“_”或者"-"，API名称长度建议不超过150字符。

例如：易于理解的API名称应为“查询虚拟机列表”/“ListServers”、“创建VPC网络”/“CreateVPC”

API描述信息必须易于理解，表述准确

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

• API描述信息要易于理解，字面表述准确，能说明API的用途，场景及约束。
• API描述信息建议使用Markdown格式编写，便于生成对应API文档，API描述信息长度建议不超过2000字符。

例如：发布API用于查询虚拟机列表。良好的API描述应为“通过虚拟机名称、IP地址、虚拟机型号查询当前租户下的虚拟机列表，列表包括虚拟机名称，所属VPC、虚拟机IP、虚拟机型号、操作系统版本。”

API文档按照模板进行写作

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

API请求尽量少使用自定义消息头

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

标准消息头及其取值格式按照参考标准，并尽量最小化添加自定义消息头。

所有消息头命名格式一致，自定义消息头命名规范：用连词符“-”分隔单词，采用大驼峰方式如X-APIG-TOKEN。

API响应报文使用分页，避免超长列表数据返回

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

• 获取资源集合的API建议支持分页。当资源数量较多时服务的查询API需要支持分页，避免一次查询获取的资源数量过多。
• 不支持分页查询，则服务应该要设置一个显示条数的默认值，避免一次返回过多资源。默认返回数量需要在接口参考中对外说明，避免调用者以为查询出了全量信息。查询条件中可以设定查询数量(limit)，位移量(offset)。查询资源列表需要返回符合查询条件的资源总数(count)、查询数量(limit)、位移量(offset)。

举例：查询虚拟机从第10条开始，查询后100条。

请求

GET /ecs/v1/projects/xxxxx/servers?offset=10&limit=100

响应

{
"resources":[
   {
     "id":"xxx",
},
…
   {
     "id":"xxx",
   }],
  "offset":10,
  "limit":100,
  "count":1540
}

API入参/出参设计必须考虑开发者易于使用

本条规则是Should类型的扩展规则，可提升API调用者的使用体验。

API设计的输入参数开发者要易于获取，输出参数要让开发者易于理解。降低开发者使用API的使用成本，提升API使用体验。避免API的输入参数要通过多次前置条件API的查询获得。