API说明书规范

   

目录

1       前言

1.1         编写目的

1.2         预期读者

1.3         关于API设计开发

2       API公共说明

3       文档API索引

4       单个API说明

4.1         API基本信息

4.2         API输入参数

4.2.1          参数分类

4.2.2          参数类型

4.2.3          参数说明表格

4.3         API响应结果

4.3.1          API响应结果说明示例

4.4         API附录

 

 

1    前言

1.1   编写目的

信息系统不可避免会与三方系统产生交互，本文将会定义信息系统体系下所有接口文档的一些通用约定。

API设计开发完成后，在保证API完整性和稳定性的情况下，需要对API接口进行详细的说明，本文档将约定如何对API接口进行说明。

注：本文档中所提及接口，都是信息系统对外提供的接口，接口作为被调用方，而不是指三方系统需要ERP去调用的接口。

1.2   预期读者

  • 系统接口设计开发人员
  • 系统接口使用人员
  • 系统三方对接公司

1.3   关于API设计开发

为信息系统开发的API需要仔细考虑，API地址名称、API输入参数、API返回值都应经过严格推敲，API是提供外部三方调用，需要经过严格测试，特别是对于会修改系统数据的API要有严格的参数验证和安全性验证。

API开发设计相关主题，不在本文档讨论范围内，具体请阅读《API设计开发规范》。

 

2    API公共说明

API公共说明需要明确API相关公共属性，包含但不局限于以下表格内容。

API集名称

例如：库房管理系统接口（Warehouse Management System API）

API集说明

例如：围绕半成品立体仓库，提供库房相关商品信息、商品数量信息、商品库位信息的查询，提供库房相关盘点信息的提交，提供入库出库等操作的执行。

API基地址

API所在IP或域名

例如 api.huaisheng.wang

支持协议

Http、Https或其它支持的协议

API基本结构

应对API中支持的输入或相应数据结构进行规约，并提供详细的说明。

例如：所有API不管成功或错误，HttpStatus状态码都返回200。

具体的执行结果

  1. {
  2.     "return_code": "0",
  3.     "message": "",
  4.     "success": true
  5.     "result": {
  6.         "page_index": 2,
  7.         "total_count": 52,
  8.         "page_count":20,
  9.         "rows": list<T>
  10.     }
  11. }

其中return_code在不为0时，代表错误码，可以据此排查错误字典，获取错误具体类型。

message在success=true时为空，否则为错误码对应的错误描述

success为true代表成功，为false代表出现异常

result为成功时的结果信息，success=false时为空

鉴权说明

需要对API的鉴权方式进行详细说明。

例如：

API必须包含鉴权参数appkey、userid、timestamp和sign，这4个参数是所有接口都必须有的，服务后端会使用保存的appsecret对sign进行验证，timestamp有效时间20s，userid为登录用户名。鉴权参数需要以请求参数的方式提供，不能放入RequestBody中。

API规约

应对API命名、入参、响应结果、字段名称、对象定义等进行规约，并在公共说明中体现。

例如：

API命名必须体现API的实际意义，一目了然，通过名称就可以基本确定API的作用，命名采用完整英文单词，多个单词用下划线分隔，名称不区分大小写。例如get_employee_list、get_user

…………

3    文档API索引

尽可能提供所有支持的API列表，API列表项点击后跳转到对应的API说明，列表格式参考以下表格。

API地址

API中文名

API说明

api/values/getvalues

获取XXXX值

 

4    单个API说明

API文档需要对每一个对外提供的接口进行详细的说明，详细说明至少包含API基本信息、API输入参数、API响应结果、API中涉及到的所有对象、枚举等内容。

4.1   API基本信息

API类别

获取数据、变更数据

Http请求方法

GET、POST、PUT、DELETE等

API地址

不包含基地址的Api访问地址，在使用时结合协议、API基地址才成为真实的API调用地址

例如：

协议“https”，基地址“api.huaisheng.wang”，

API地址“api/orders/getlist?kind={kind}”

组合后的真实访问地址为：

https://api.huaisheng.wang/api/orders/getlist?kind=1

API说明

对API的中文说明信息

例如：上面单元格API地址对应“获取类型为1的订单列表”。

4.2   API输入参数

4.2.1  参数分类

API参数分为三种：URL路径参数、URL查询参数、请求体参数。

URL路径参数

URL Path Parameter

比如api/orders/getlist/{sealerid}?orderkind={orderkind}

其中的{sealerid}就是路径参数

对应具体的请求api/orders/getlist/1?orderkind=2

路径参数sealerid=1

查询参数orderkind=2

URL查询参数

URL Query Parameter

比如/api/test?a=1&b=2，其中a和b就是查询参数

请求体参数

Request Body Parameter

调用方需要将参数按给的的格式构造在请求的body里面，发送到对应的API地址。在我们提供的API中，通常情况下请求体参数为JSON格式（API的Content-Type为application/json）。

4.2.2  参数类型

API说明书需要对入参的参数类型进行详细的说明。

例如：

API支持所有参数类型如下表格所示：

参数类型

说明

string

字符串类型

Integer

整型

long

长整型

float

浮点型

boolean

布尔型

对象

Object

例如：

TestPerson

 

需要对对象所有属性进行说明，说明格式如下表格所示

属性名

中文名

类型

备注

Name

姓名

String

 

Age

年龄

Integer

 

 

对象集合

Collection of Object

例如：

Collection of TestPerson

需要对对象所有属性进行说明，说明格式如下表格所示

属性名

中文名

类型

备注

name

姓名

string

 

age

年龄

integer

 

其它

依据实际情况添加相关说明。

比如对最常返回的对象进行特殊说明

4.2.3  参数说明表格

每个API需要对参数进行表格化说明，包含参数、名称、类型、是否必须、备注，表格格式如下：

参数

名称

类型

必须

备注

age

年龄

integer

Yes

 

4.3    API响应结果

需要对API响应结果进行详细说明，包含响应数据类型，响应Http状态码，响应详细格式及说明等。在API说明文档中需要对响应内容给出示例。

4.3.1  API响应结果说明示例

API支持json和xml两种格式，会依据请求客户端的需要返回对应类型的数据。

JSON格式

Mime类型：APPLICATION/JSON,TEXT/JSON

Sample:

{
  "return_code": 1,
  "success": true,
  "message": "sample string 2",
  "result": [
    {
      "Name": "sample string 1",
      "Age": 2
    },
    {
      "Name": "sample string 1",
      "Age": 2
    }
  ]
}

XML格式

Mime类型：APPLICATION/XML,TEXT/XML

Sample:

<ArrayOfTestPerson xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Models.Dto.Posts">
  <Message>sample string 2</Message>
  <Result xmlns:d2p1="http://schemas.datacontract.org/2004/07/Models.Dto.Tests">
    <d2p1:TestPerson>
      <d2p1:Age>2</d2p1:Age>
      <d2p1:Name>sample string 1</d2p1:Name>
    </d2p1:TestPerson>
    <d2p1:TestPerson>
      <d2p1:Age>2</d2p1:Age>
      <d2p1:Name>sample string 1</d2p1:Name>
    </d2p1:TestPerson>
  </Result>
  <ReturnCode>1</ReturnCode>
</ArrayOfTestPerson>

4.4   API附录

如果接口中使用到一些特定的对象或数据，需要进行额外的说明，这时需要为API添加附录节（例如API接口的入参或者返回值是有固定的取值枚举时，一般需要在附录里面列出具体的枚举值）。

例如：接口返回人员信息中包含人员类型枚举

人员类型枚举

名称

中文

值

备注

Manager

管理人员

1

 

OfficialStaff

正式员工

2

 

TempStaff

临时员工

3

 

……

 

 

 文章作者：花生（OutMan）

发布地址：http://www.cnblogs.com/WangHuaiSheng/ 

发布时间：2018-04-25

本文版权归作者和博客园共有，欢迎转载，

但未经作者同意必须保留此段声明，

且在文章页面明显位置给出原文连接。

  

  

posted @ 2018-04-27 13:17  读喜爱  阅读(5882)  评论(0)  编辑  收藏  举报