软件接口(API)

一、分类 

1、REST API（restful风格的API）

①     发送请求进行CRUD哪个操作由请求方式来决定

②     同一个请求路径可以进行多个操作

③     请求方式会用到GET/POST/PUT/DELETE

2、非REST API（restless风格的API）

①     请求方式不决定请求的CRUD操作

②     一个请求路径只对应一个操作

③     一般只有GET/POST

CRUD：是指在做计算处理时的增加(Create)、检索(Retrieve)、更新(Update)和删除(Delete)几个单词的首字母简写。crud主要被用在描述软件系统中数据库或者持久层的基本操作功能。

 

二、组成部分

一个合格的接口文档应该包括以下六项内容：

（一）接口名称：用来标识各个接口的简单说明，例如登录接口，获取图书列表接口等；

（二）接口URL：接口的调用地址；

（三）调用方式：接口的调用方式，例如GET或POST；

（四）参数格式：接口需要传递的参数，每个参数需包含参数名称、参数类型、是否必选、参数说明这4项内容；

（五）相应格式：接口的返回值的详细描述，一般包含数据名称、数据类型、说明这3项内容；

（六）返回实例：（此为可选项）通过对象的形式，例举服务器返回数据的结构。

 

三、接口文档示例

文档信息
版本信息

版本号	创建时间	作者	受控状态	审核	校对
0.1	2021.05.26	李飞	受控

 

 

 

修改信息

 

序号	修改后版本号	修改日期	修改人	修改原因	修改内容
1	0.5	2021.05.26	李飞	填充数据	用户-新增接口

 

 

 

***********************************************************************************

接口信息
用户设置（接口名称）

新增

请求地址：http://www.baidu.com
请求方法：POST
请求参数示例：

id=6&nameLike=张三

请求头：

Content-Type: application/json;charset=UTF-8

请求参数说明：

参数名称	参数类型	是否必填（必选）	默认值	参数说明
id	Number	否		图书ID
bookname	String	否		图书名称
author	String	否		图书作者
publisher	String	否		出版社

 

 

 

 

 

 

 

请求体示例：

 {
    "rearNo": "",
    "feeName": "后勤报销测试",
    "feeCode": "2",
    "unit": "2",
    "amount": "6",
    "price": "10",
    "totalPrice": "60",
    "rearBy": "莫",
    "orgId": "depart2",
    "convoyId": "CD-SCCD",
    "rearDate": "2018-05-04 00:00:00",
    "remark": ""
  }

 

返回结果参数说明：

数据名称	数据类型	说明
status	Number	200成功；500失败；
msg	String	对status字段的详细说明
data	Array	图书列表
*id	Number	图书ID
*bookname	String	图书名称
*author	String	图书作者
*publisher	String	出版社

 

 

 

 

 

 

 

 

 

 

返回结果示例：