Restful API接口规范

REST（Representational State Transfer）表述性状态转换，REST指的是一组架构约束条件和原则。 如果一个架构符合REST的约束条件和原则，我们就称它为Restful架构。
一个简单的例子来看Restful和非Restful

非restful
新增用户：http://127.0.0.1:8088/adduser
修改用户：http://127.0.0.1:8088/putuser
删除用户：http://127.0.0.1:8088/deleteuser
查询用户：http://127.0.0.1:8088/getuser

restful
新增用户：POST http://127.0.0.1:8088/user
修改用户：PUT http://127.0.0.1:8088/user
删除用户：DELETE http://127.0.0.1:8088/user
查询用户：GET http://127.0.0.1:8088/user

可以看到对于非restful而言，它们是以不同的url来完成对应的请求，而对于restful而言，它们访问的url是一样的，但是HTTP方法动词不同，它们用HTTP STATUS/CODE定义操作结果。

restful的好处

URL具有很强可读性的，具有自描述性
规范化请求过程和返回结果
资源描述与视图的松耦合
可提供OpenAPI，便于第三方系统集成，提高互操作性
提供无状态的服务接口，降低复杂度，可提高应用的水平扩展性

规范整理

版本号

有三种方式放版本信息
1、在uri中放版本信息：GET /v1/users/1
2、Accept Header：Accept: application/json+v1
3、自定义 Header：X-Api-Version: 1
命名版本号可以解决版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。上面所列的三种方式也是比较简单方便的一种

URL是名词

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

请求方式

GET：查询
POST：创建单个资源
PUT：更新单个资源（全量），客户端提供完整的更新后的资源
DELETE：删除

	安全性	幂等性
GET	✔	✔
POST	✗	✗
PUT	✗	✔
DELETE	✗	✔

安全性：不会改变资源状态，可以理解为只读的；
幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。

相应参数

json格式

状态码

200~299段 表示操作成功：

200 操作成功，正常返回

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

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

300 参数类型错误

301 参数格式错误

302 参数超出正常取值范围

303 token过期

304 token无效

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

400 找不到地址

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

500 服务器代码异常