API设计指南 一个接口文档模板的最佳实践

Posted 2021-05-01 码农 资深

1. 基础说明

1.1 背景

API(Application Programming Interface,应用程序编程接口)是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。API除了有应用“应用程序接口”的意思外，还特指API的说明文档，也称为帮助文档。

1.2 基本约束

1.2.1 字符集

• 所有接口字符集采用UTF-8。

1.2.2 返回类型约束

• 所有接口返回必须是严格定义的JSON类型。

1.2.3 接口版本约束

• 不允许发布无版本号的接口。

• 接口版本首先解决的是一组接口的版本问题。

1.3 请求公共约束

请求的基本模板：

curl -X[HTTP METHOD] -H "Content-Type: application/json" -H "[token-info]:"
"https://api-[env-name].[groupname].domain.io/[client-group]/[service-group]/
[version]/[endpoint]" -d '{
  "head": [meta-parameters],
  "body": [content]
}'

1.4 URL整体规划

1.4.1 域名规范

• https://api-[env-name].[groupname].domain.io/[client-group]/[service-group]/[version]/[endpoint]

1.4.2 域名规则

• 开发环境：https://api-dev.payment.domain.io/

• 测试环境：https://api-test.payment.domain.io/

• 预演环境：https://api-staging.payment.domain.io/

• 线上测试环境：https://api-onlinetest.payment.domain.io/

• 生产环境：https://api.payment.domain.io/

• 其中线上测试环境是上线过程中备用，比如线上一共3台生产环境服务器，将其中一台从生产环境切掉，更新程序并且将域名指向它，测试完之后再将生产环境流量切换过来。

1.5 基本数据类型约定

此约定是系统整体容错的一部分，但是无论接口使用者还是生产者，都不应该因为此容错而减少自己模块本来需要的容错工作。

1.6 公共输入参数规范

1.7 公共返回对象约定

{
  "responseCode": [responseCode],
  "responseInfo": {
    "userMessage": [userMessage],
    "internalMessage": [internalMessage],
    "guideline": [guideline link]
  },
  "link": {
    "document":" https://[domain]/docs#zoos",
    "href":[uri-info],
    "title":[doc-title],
    "type":"application/[vnd.yourformat]+json"
  },
  "responseData":[responseData]
}

1.8 公共错误编码及说明

1.9 公共数据字典

2. 订单服务

2.1 查询订单列表

2.1.1 接口规范

2.1.2 输入参数示范

curl -XGET -H "Content-Type: application/json" -H "Access-Token:abcd1234" "https://api-dev.haitao.domain.io/mobile/data-platform/v1/orders/base-orders" -d '{
  "head": [meta-parameters],
  "body": {
    "pageSize":10,
    "pageNo":1
  }
}'

2.1.3 返回参数示范

{
  "responseCode": [responseCode],
  "responseInfo": {
    "userMessage": [userMessage],
    "internalMessage": [internalMessage],
    "guideline": [guideline link]
  },
  "link": {
    "document":" https://[domain]/docs#zoos",
    "href":[uri-info],
    "title":[doc-title],
    "type":"application/[vnd.yourformat]+json"
  },
  "responseData": {
    "pageCount": 12,
    "pageNo": 2,
    "data": {
    }
  }
}