第二节 平台API接口标准规范

一、目的

本规范旨在为平台各个用户企业或单位的各业务系统之间业务复用及整合的API提供接口调用与交互规范。同时，也作为未来平台业务系统内各应用模块之间以及各业务系统之间，以服务接口的方式，提供数据和各种功能的一种尝试。

二、规范适用说明

本规范仅适用于由客户端发起调用请求、GET/POST/PUT/PATCH/DELETE提交数据请求文本数据结果的API。基于https协议，统一使用UTF 8编码规则，通过JSON数据格式进行响应。

三、接口示例

接口描述：用户登录，系统返回token及用户相关数据。

URL：https：//sy.nrc.ac.cn/api/v1/public/login/。

方法：POST。

请求参数：如表3-3、表3-4、表3-5。

接口返回json示例：

四、基本规范

（一）URL设计

完整的URL接口包含以下部分：

主域名+/api/版本号/模块标识/业务名称/。

以登录接口为例：

https：//sy.nrc.ac.cn/api/v1/public/login/

public表示登录模块，login表示是登录业务。（表3-6）

（二）请求方法

接口遵循restful风格设计，允许使用的请求方法如表3-7。

（三）系统级参数约定

以下参数是由API平台系统定义的，各api请求必须传递Header参数。（表3-8）

（四）应用级参数通用约定

各业务系统应遵守API平台系统规范中应用级通用参数的约定。（表3-9）

（五）响应数据

API当前仅支持JSON响应格式，正常响应包括符合如下规范的json字符串。

https响应头中的Content-Type指定为application/json，charset=utf-8。

字符串编码格式是UTF 8。（表3-10）

五、在线接口文档

企业注册、验证、基础信息、种源信息、种植、田间管理、采收、加工、仓储、仓储养护、质检、销售、运输等相关功能的接口。（图3-6，表3-11）

https：//sy.nrc.ac.cn/doc/web/#/2?page_id=8