WebAPI规范

接口定义形式

如何定义

所有的Web API接口根据用途可以分为两类，一个类是资源管理类的接口，遵循REST原则，另一类是指令类。

一般情况下的接口所操作的对象均为数据资源，所以在接口定义层面需要遵循REST原则，具体表现为以下几个方面：

接口表述为资源定义，路径中仅存在资源相关描述，不存在逻辑动作描述.

例如： /api/v1/resource/image/122 表示为资源管理模块下ID为122的图片资源 /api/v1/resource/images 表示资源管理模块下的所有图片资源
使用常用HTTP Method表示操作描述

GET表示获取，POST表示保存，PUT表示修改，DELETE表示删除
其中POST可以表述为创建或者创建保存，通常情况下若资源不存在额外创建初始化的操作，则默认POST为创建或保存，此时不需要额外提供PUT接口用于修改更新。
GET 用于获取列表或者获取单个资源详情，以实际接口定义为准，所有的GET接口不得存在副作用。

根据实际业务需要，存在部分业务逻辑需要对多个资源进行业务操作或者专有的业务逻辑处理，使用资源定义无法表述该操作动作的时候，则使用使用指令类的接口规范，使用说明如下：

接口表述为的动作定义，路径中除说明对于资源模块以外，需说明该接口所表述的具体动作

例如： /api/v1/resource/video/saveAs 表示进行视频转存。
若非实际接口需要，则尽可能不提供万能接口，即接口本身定义模糊，使用参数说明所有的操作和数据。
接口仅使用POST表示操作描述

接口参数一般采用 JSON 格式，含文件类型使用FormData类型。
参数需说明具体操作对象信息，参考表述说明，参数本身应不包含操作说明。
在实际接口开发中，如果提供的单接口同时支持创建和更新逻辑时，约定只有主键值不存在时，执行创建逻辑，其他情况执行更新逻辑。

例如伪代码可能如下：

var item = db.query(id);
if(item != null) 
update item
else
if(id != 0) return create fail;
        create item

如何书写

对于所有的接口，一般采用小驼峰格式，全路径小写，可以使用数字、字母、下划线，但是数字只能用于版本和资源ID，尽可能不适用缩写，可以有限使用通用常规缩写，禁止使用自定义缩写。

版本管理

接口版本管理不做明确限制，依据各模块使用情况进行统一规范。但使用到的版本信息，需要在路径中体现，不采用Header 或者 QueryString的形式。

参数格式

API参数分为两类，参考格式定义，已基本可以确定参数格式。
通常情况下，使用 QueryString 作为非必须查询条件，允许接口调用时不传递该参数，在接口中则需要通常以null填充，非可空类型则需指定默认值。
QueryString禁止用于具有变更属性的参数传递。
除文件传输使用FormData类型之外，其他情况下一律使用JSON格式进行参数的传递，消息内容的定义，参照格式定义进行。

接口升级须知

所有的API接口在升级的时候，务必兼容过去的接口调用，不得非兼容性变动接口定义或者参数格式，造成调用失败。兼容性需考虑一下几部分：

接口定义
接口参数
接口的返回值

对于存在不可兼容性变化的接口，可通过升级接口版本号或者定义新接口（新老接口共存）的形式提供业务接口。

常用接口格式

常规数据接口

根据接口定义规范：

所有的数据接口中，仅需包含用于描述资源实体的属性字段或者关系字段
若资源接口同时存在查询和保存，则字段定义需保持一致，即查询返回字段可直接作为保存参数使用
所有的字段格式统一采用 camelCase

列表数据接口

列表式数据根据数据特性和数量可采用列表数据或者分页数据，通常的判断标准为，常规数据总量不超过20个，或者数据特性不支持分页，则采用列表数据，即返回包含所有数据数组的形式，可根据需求增加筛选字段。
若采用分页数据格式，则接口必须支持 index,size作为查询条件，其中 index 和 size 的最小值为1。
返回数据格式为：

{
    "index": 1,
    "size": 10,
    "total": 1,
    "data": []
}

其中返回数据的index和size 为查询所提供的index 和 size ，total 为符合条件的数据总量，data 为实际的数据列表。

错误接口信息

所有的接口但凡在正常情况，都不会提供任何的异常信息，所有常规的异常信息都需要在400状态码中，异常的处理详情可参考【异常处理规范】。所有异常接口的格式均为：

{
    "error": {
        "code" : int32, // 错误代码
        "message": string, // 错误描述
    }
}

错误代码的时候参见：全局错误码

状态码使用

200：所有正常接口调用，任何逻辑正常，业务正常均返回200
400：所有常规异常接口调用，即在业务逻辑范围之后的，接口参数错误、业务数据错误、业务逻辑错误等
401：接口需要验证，即接口需要有登录验证信息，仅限未登录的情况
403：接口权限受限，即当前登录凭证不具有接口调用所需的特定权限
500：服务异常，任何未捕获的业务代码异常或服务运行异常

API接口对接检查表

API接口对接检查表 ** 以下规则适用于所有接口定制场景，包含但不限于系统API、开放平台API、代理接口API、定制项目API 等。

语义化

接口定义上是否可以理解，容易理解

接口使用小驼峰格式(camelCase)
接口路径中仅接口版本和资源ID使用纯数字命名
接口中的资源命名使用规范命名
不允许使用非规范的命名缩写
资源类接口需指明相应资源
指令类接口需指明业务逻辑
查询接口不允许出现副作用
接口参数不得使用魔法值
状态字段尽可能使用枚举或者有意义的字符串，不得使用未经定义的数字参数
仅在参数状态可以表示为开、关和未知时使用布尔类型
创建/保存类接口，需要返回创建/保存资源的ID
QueryString仅作为可选查询参数

完善性

接口组合是否完整提供相关业务逻辑功能

资源类需要至少提供以下类型接口
- 创建资源/更新资源（保存资源）（POST/PUT）
- 详情查询（GET）
- 列表查询（GET）
- 删除（DELETE）
同版本接口需要保持逻辑完整性
接口文档或注释需要提供对接口使用范围的完整性描述
接口文档或注释需要提供对接口使用限制的完整性描述
接口需要防御非法输入
分阶段的接口需要检查当前业务阶段的有效性

一致性

接口说明和接口的定义是否一致

接口字段的定义需要和接口说明保持一致
接口逻辑需要和接口说明文档保持一致
统一资源在不同接口中的命名需一致
接口的功能需要和接口命名定义保持一致
接口的错误信息需要与当前接口业务保持一致

可维护性

接口的定义是否保持整洁，是否便于扩展

接口可传入参数不能超过7个
新增参数需要给定默认值或者允许可空
一个接口只处理一个事情
已发布的接口不得进行破坏性更新
已过期的接口需要用[Obsolete]标记
破环性更新需要升级接口版本
批量接口需要设定数量上限

安全性

是否有足够的权限校验，避免信息泄露

非公开接口需要进行用户身份验证
非公开接口需要进行用户权限验证
公开接口需请求来源可溯
对接口传入参数进行合法性校验，避免非法数据篡改
对接口查询信息进行合法性校验，避免非法数据泄漏

合规性

接口的定义是否符合相关开发者规范

接口不得泄漏非完全公开数据

Table of Contents