更新时间:2023-09-27 GMT+08:00
分享

易用性

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对外开放时,API文档建议使用统一的模板,以便保持API参考文档的一致性,易于开发者理解。在API参考文档中必须包含如下内容:
  • API目录,包括本次提供API的列表信息。
  • API名称及API功能介绍。
  • API请求方法和URI。
  • API请求参数说明,包括Header、Query参数,需要明确字段内容和取值范围。
  • API请求Body内容,Body内容需要明确请求结构体内容及各个字段的取值范围。
  • API响应状态码,状态码及对应的说明。
  • API响应参数说明包括Header参数,需要明确字段内容和取值范围。
  • API正常响应Body内容,正常响应Body内容需要明确响应结构体内容及各个字段的取值范围。
  • API异常响应Body内容,异常响应Body中描述及说明。

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的查询获得。

相关文档