企业采购平台 RESTful 接口设计文档
一、 接口规则说明
基本规则
1. 当标准合理的时候遵守标准。
2. API应该对程序员友好,并且在浏览器地址栏容易输入。
3. API应该简单,直观,容易使用的同时优雅。
4. API应该具有足够的灵活性来支持上层UI。
5. API设计权衡上述几个原则。
接口命名规范
1. 路径(EndPoint)
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
在URL设计中,任何描述对象属性的参数,都应该按照层级结构体现在URL中。而且,该URL应该是无状态的。例如:
需求: 查询一个项目->竞价项目->根据code查询->只查询一条
竞价类型 项目集合(复数) code
抽象为接口:/ competition / projects / {code}
接口定义的合理性可以从语义上进行评价,如果去掉URL分隔符 ’/’,它会是一句完整的英语句子或者生活中合理的物件命名。上面的例子就是 competitionProject007,即竞价项目007。
当查询一类集合时,直接请求该资源路径。过滤的信息放在请求头内。
RequestHeaders: {from:1, to:100, userId: 3 }; uri: /competition/projects
2. 动词(Http Request Method)
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面五个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
定义SpringMVC 接口时,使用以下注解对URL进行动词描述
@DeleteMapping
@PatchMapping
@PutMapping
@GetMapping
@PostMapping
下面是接口定义的例子
GET /competition/projects:列出所有竞价项目
POST /competition/projects:新建一个竞价项目
GET /competition/projects/{code}:获取某个指定竞价项目的信息
PUT /competition/projects/{code}:更新某个指定竞价项目的信息(提供该竞价项目的全部信息)
PATCH/competition/projects/{code}:更新某个指定竞价项目的信息(提供该竞价项目的部分信息)
DELETE /competition/projects/{code}:删除某个竞价项目
GET/competition/projects/{code}/sections:列出某个指定竞价项目的所有标的物
DELETE /competition/projects/{code}/sections/{objectId}:删除某个指定竞价项目的指定标的物
3. 过滤(Filter)(非标准)
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?project_type=1:指定筛选条件
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /projects/{code}/sections 与 GET /sections?projectCode=code 的含义是相同的。
4. 返回值 (Return Value)
GET/collection:返回资源对象的列表(数组)
GET/collection/resource:返回单个资源对象
POST/collection:返回新生成的资源对象
PUT/collection/resource:返回完整的资源对象
PATCH/collection/resource:返回完整的资源对象
DELETE/collection/resource:返回一个空文档
5. 状态码 (Status Code)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。
200 OK | [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。 |
201 CREATED | [POST/PUT/PATCH]:用户新建或修改数据成功。 |
202 Accepted | [*]:表示一个请求已经进入后台排队(异步任务) |
204 NO CONTENT | [DELETE]:用户删除数据成功。 |
400 INVALID REQUEST | [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。 |
401 Unauthorized | [*]:表示用户没有权限(令牌、用户名、密码错误)。 |
403 Forbidden | [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。 |
404 NOT FOUND | [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。 |
406 Not Acceptable | [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。 |
410 Gone | [GET]:用户请求的资源被永久删除,且不会再得到的。 |
422 Unprocesable entity | [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。 |
500 INTERNAL SERVER ERROR | [*]:服务器发生错误,用户将无法判断发出的请求是否成功。 |
二、 系统接口详细设计
1. Project
接口(SpringMVC) | 操作 | 描述 |
/{type}/projects | POST | 项目入库(创建) |
GET | 项目列表 | |
/{type}/projects/{code} | GET | 根据Code获取项目 |
DELETE | 删除指定项目 | |
PUT | 全量更新指定项目 | |
PATCH | 更新项目属性 | |
/{type}/projects/base{code} | GET | 查询项目基本信息 |
2. Section
接口(SpringMVC) | 操作 | 描述 |
/sections | POST | 创建标段 |
GET(?projectCode) | 项目下所有标段 | |
PUT | 批量创建标段 | |
/sections/{objectId} | GET | 根据id获取标段 |
DELETE | 删除指定标段 | |
PUT | 全量更新标段 | |
PATCH | 更新标段基本信息 |
//TODO 接口还需设计,先作为例子抛个砖,希望能引个玉出来