restful api接口规范

简介：

REST：英文representational state transfer直译为表现层状态转移，或者表述性状态转移。

为何须要Restful？

URL具备很强可读性的，具备自描述性

规范化请求过程和返回结果

资源描述与视图的松耦合

可提供OpenAPI，便于第三方系统集成，提升互操做性

提供无状态的服务接口，下降复杂度，可提升应用的水平扩展性

一、版本号

命名版本号能够解决版本不兼容问题，在设计 RESTful API 的一种实用的作法是使用版本号。通常状况下，咱们会在 url 中保留旧版本号，并同时兼容多个版本

【GET】  /v1/users/{user_id}  // 版本 v1 的查询用户列表的 API 接口

【GET】  /v2/users/{user_id}  // 版本 v2 的查询用户列表的 API 接口

二、资源路径

URI 不能包含动词，只能是名词（命名名词的时候，要使用小写、数字及下划线来区分多个单词）。

资源的路径应该从根到子依次以下:

/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}

【POST】  /v1/users/{user_id}/roles/{role_id} // 添加用户的角色

 

有的时候，当一个资源变化难以使用标准的 RESTful API 来命名，能够考虑使用一些特殊的 actions 命名。

/{resources}/{resource_id}/actions/{action}

【PUT】  /v1/users/{user_id}/password/actions/modify // 密码修改

 

三、请求方式

【GET】          /users                # 查询用户信息列表

【GET】          /users/1001           # 查看某个用户信息

【POST】         /users                # 新建用户信息

【PUT】          /users/1001           # 更新用户信息(所有字段)

【PATCH】        /users/1001           # 更新用户信息(部分字段)

【DELETE】       /users/1001           # 删除用户信息

 

【PATCH】通常不用，用【PUT】

四、查询参数

RESTful API 接口应该提供参数，过滤返回结果。

【GET】  /{version}/{resources}/{resource_id}?offset=0&limit=20

 

五、响应参数

JSON格式（code、data、msg）

 

六、状态码

使用适合的状态码很重要，而不该该所有都返回状态码 200

状态码，可根据如下标准按照项目扩展自身状态码：

200~299段 表示操做成功：

200 操做成功，正常返回

201 操做成功，已经正在处理该请求

300~399段 表示参数方面的异常

300 参数类型错误

301 参数格式错误

302 参数超出正常取值范围

303 token过时

304 token无效

400~499段 表示请求地址方面的异常：

400 找不到地址

500~599段 表示内部代码异常：

500 服务器代码异常