文档首页/ API中心 API Hub/ 产品介绍/ 附录-API治理规范指导/ 规范要求/ API生产/ 易用性
更新时间：2023-09-27 GMT+08:00
查看PDF
分享

易用性

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

父主题： API生产

相关文档