content
1 Preface
1.3 About API design and development
4.2.1 Parameter classification
4.2.2 Parameter types
4.2.3 Parameter description table
4.3.1 Example of API response result description
4.4 API Appendix
1 Introduction
1.1 Purpose of writing
The entire ERP information system will inevitably interact with the three-party system. This document will define some common conventions for all interface documents under the information system system.
After the API design and development is completed, in the case of ensuring the integrity and stability of the API, the API interface needs to be described in detail. This document will stipulate how to describe the API interface.
Note: The interfaces mentioned in this document are all the interfaces provided by the ERP information system. The interface is the called party, not the interface that the third-party system needs to call from the ERP .
1.2 Intended audience
- ERP system interface design developer
- ERP system interface user
- ERP system tripartite docking company
1.3 About API design and development
The API developed for the information system needs to be carefully considered. The API address name, API input parameters, and API return value should be strictly scrutinized. The API provides external third-party calls and needs to be strictly tested, especially for the API that will modify the ERP system data. There is strict parameter validation and security validation.
Topics related to API development and design are beyond the scope of this document. For details, please read "API Design and Development Specifications" .
2 API public description
API public descriptions need to specify API-related public attributes, including but not limited to the following table content.
| API set name |
For example: Warehouse Management System API |
| API set description |
For example, around the three-dimensional warehouse of semi-finished products, it provides the query of warehouse-related commodity information, commodity quantity information, and commodity location information, provides the submission of warehouse-related inventory information, and provides the execution of operations such as warehousing and warehousing. |
| API base address |
The IP or domain name of the API For example api.huaisheng.wang |
| supporting agreement |
Http, Https or other supported protocols |
| API basic structure |
The inputs or corresponding data structures supported in the API should be specified and detailed descriptions should be provided. For example: All APIs return 200 regardless of success or error. specific execution results
When return_code is not 0, it represents the error code, which can be used to check the error dictionary and obtain the specific type of error. message is empty when success=true, otherwise it is the error description corresponding to the error code success is true for success, false for an exception result is the result information when success, empty when success=false |
| Authentication Instructions |
The authentication method of the API needs to be described in detail. E.g: The API must include the authentication parameters appkey, userid, timestamp and sign. These four parameters are required for all interfaces. The service backend will use the saved appsecret to verify the sign. The timestamp is valid for 20s, and the userid is the login user name. Authentication parameters need to be provided as request parameters and cannot be placed in RequestBody. |
| API specification |
API naming, input parameters, response results, field names, object definitions, etc. should be specified, and reflected in the public description. E.g: API naming must reflect the actual meaning of the API. It is clear at a glance that the function of the API can be basically determined by the name. The naming uses complete English words, multiple words are separated by underscores, and the names are not case-sensitive. For example get_employee_list, get_user ………… |
3 Document API Index
Provide a list of all supported APIs as much as possible. Click on the API list item to jump to the corresponding API description. For the list format, refer to the following table.
| API address |
API Chinese name |
API description |
| api/values/getvalues |
Get XXXX value |
|
4 single API description
The API documentation needs to provide a detailed description of each externally provided interface. The detailed description includes at least basic API information, API input parameters, API response results, all objects involved in the API, and enumerations.
4.1 API Basic Information
| API category |
Get data, change data |
| Http request method |
GET、POST、PUT、DELETE等 |
| API address |
The Api access address that does not contain the base address becomes the real API call address when used in combination with the protocol and API base address . E.g: Protocol "https", base address "api.huaisheng.wang", API地址“api/orders/getlist?kind={kind}” The combined real access address is: |
| 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
需要对对象所有属性进行说明，说明格式如下表格所示
|
||||||||||||
| 对象集合 |
Collection of Object 例如： Collection of TestPerson 需要对对象所有属性进行说明，说明格式如下表格所示
|
||||||||||||
| 其它 |
依据实际情况添加相关说明。 比如对最常返回的对象进行特殊说明 |
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 本文版权归作者和博客园共有，欢迎转载， 但未经作者同意必须保留此段声明， 且在文章页面明显位置给出原文连接。 |