REST ful API

RESTful:用URL定位资源、用HTTP动词（GET、POST、PUT、DELETE)描述操作。

RESTful API就是REST风格的API，即rest是一种架构风格，跟编程语言无关，跟平台无关，采用HTTP做传输协议。

RESTful API就是一套协议用来规范多种形式的前端和同一个后台的交互方式。

前后端分离之后，我们就不用在前端页面中写jstl，el表达式了，甚至连jsp都不需要使用了，直接html即可，前端跟后端的交互使用ajax+json这样符合rest风格的架构即可，

这样做的好处就是：

项目的分工更加明确了

实现了前后端的解耦

可以将前端和后端部署到不同的服务器上来减轻服务器的压力

前后端代码在不同的服务器上，可以提高安全性

非Rest设计，以往我们都会这么写：

http://localhost:8080/admin/getUser （查询用户）

http://localhost:8080/admin/addUser （新增用户）

http://localhost:8080/admin/updateUser （更新用户）

http://localhost:8080/admin/deleteUser （删除用户）

总结：以不同的URL（主要为使用动词）进行不同的操作。

Rest架构：

GET http://localhost:8080/admin/user （查询用户）

POST http://localhost:8080/admin/user （新增用户）

PUT http://localhost:8080/admin/user （更新用户）

DELETE http://localhost:8080/admin/user （删除用户）

总结：URL只指定资源，以HTTP方法动词进行不同的操作。用HTTP STATUS/CODE定义操作结果。

Restful：遵守了rest风格的web服务便可称为Restful。

为什么需要Restful？ 

1）URL具有很强可读性的，具有自描述性

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

3）资源描述与视图的松耦合

4）可提供OpenAPI，便于第三方系统集成，提高互操作性

5）提供无状态的服务接口，降低复杂度，可提高应用的水平扩展性

• 
  
  /版本号/资源路径
  /v1/tags/{tag_id}
  /v1/users?[&keyword=xxx][&enable=1][&offset=0][&limit=20]
   

使用RESTful风格不同于普通借口命名的一点是，它规范使用/来表示资源之间的层级关系。

规范

1、版本号

命名版本号可以解决版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留旧版本号，并同时兼容多个版本

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

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

2、资源路径

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 // 密码修改

3、请求方式

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

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

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

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

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

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

【PATCH】一般不用，用【PUT】

4、查询参数

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

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

5、响应参数

JSON格式（code、data、msg）

6、状态码

使用适合的状态码很重要，而不应该全部都返回状态码 200

200~299段 表示操作成功：

200 操作成功，正常返回

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

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

300 参数类型错误

301 参数格式错误

302 参数超出正常取值范围

303 token过期

304 token无效

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

400 找不到地址

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

500 服务器代码异常

200：服务器成功返回用户请求的数据，该操作是幂等的。

201：用户新建或修改数据成功。

202：表示一个请求已经进入后台排队（异步任务）

204：用户删除数据成功。

301：永久重定向

302：暂时重定向

400：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

401：表示用户没有权限（令牌、用户名、密码错误）。

403：表示用户得到授权（与401错误相对），但是访问是被禁止的。

404：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

406：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

410：用户请求的资源被永久删除，且不会再得到的。

422：当创建一个对象时，发生一个验证错误。

500：服务器发生错误，用户将无法判断发出的请求是否成功。