Restful概念

representational state transfer 表现层状态转移, 表现层就是WEB的uri(资源)， rest指资源的状态发生变化，资源的增删改查，资源发生了改变。

访问一个资源 http://10.8.8.8/index.jsp , GET 获取资源, POST 提交数据; URI不变，但是资源变化了

**注意：rest只是论文，没有标准；后来很多人尝试，有一种风格叫restful, 如下: **

统一URL
不同的操作
达到状态转移，这种方式就是Restful

使用restful，注意的问题如下：

协议

可以使用http, https https: 更安全

http方法

对url资源执行的动作

动作(http请求方法)	说明
GET	查资源；多个，1个
POST	创建新资源；多个，1个
PUT	资源完整修改；多个，1个
PATCH	资源的某1项修改；多个，1个
DELETE	删除资源；多个，1个

使用名词

URL指向资源，表现的是资源, 应该使用名词表达，而不是动词表达

只需要名称，不要出现动词(路径，查询字符串)。动词由Http提供
英文名词统一复数

描述	错误	正确
获取多个用户	GET http://localhost/get_all_users `其中有动词`	GET http://localhost/users
获取1个 id=1的用户	GET http://localhost/user/1 `资源名词非复数`	GET http://localhost/users/1
创建多个用户	POST http://localhost/add_users `其中有动词`	POST http://localhost/users
更新1个用户 id=1的用户	POST http://localhost/update_users `其中有动词`	PUT http://localhost/users/1
删除资源 id=1的用户	POST http://localhost/users/1?action=del `查询字符串有动词`	DELETE http://localhost/users/1
id=1的用户，部分内容修改		PATCH http://localhost/users/1

对人的管理，只需要2类

列表页 /users 查加删

GET 获取; POST 添加；（与ID无关）

详情页 /users/<int:id>

GET 获取; PUT/PATCH 更新; DELETE 删除（与ID相关）

对文章的管理

/posts

/posts/<int: id>

子资源访问

描述	错误	正确
获取id=1的用户的所有文章	GET http://localhost/get_user_blogs?id=1 `其中有动词` GET http://localhost/getuserblogs?id=1 GET http://localhost/GetUserBlogs?id=1	GET http://localhost/users/1/posts
获取id=1的用户的id=2的文章		GET http://localhost/users/1/posts/2

之前的风格，是查询参数带数据。淘汰而且风格不统一

restful风格，是URL路径自然带数据。最佳实践 风格统一，代码好 1用户 2号博客

列表页 `/users`

列表页 /users 查加删
- GET 获取; POST 添加；（与ID无关）
详情页 /users/<int:id>
- GET 获取; PUT/PATCH 更新; DELETE 删除（与ID相关）

/users 默认返回所有数据，这样不行，一张表180G怎么办？数据库卡死了, 需要分页

描述	URL	描述	sql
用户查询，分页	/users?page=1&pagesize=20 对数据加要求，非业务数据查询字符串 /users/page/1 `这样好像是users下的业务` 不好	第1页20个用户	SELECT * FROM history `OFFSET (page-1)*20 LIMIT 20`;
用户查询，过滤	/users?name=tom /posts?tag=python	过滤tom用户过滤python标签的博客	SELECT * FROM history `where name="tom";`
用户查询，排序	`/users?page=1&pagesize=20&sort=name.desc` 单列排序 `/users?page=1&pagesize=20&sort=name.asc,gender.desc` 多列排序 `/users?page=1&pagesize=20&sort=-name,id` 简化默认正，-表示逆序	第1页20个用户按姓名排序	SELECT * FROM history `ORDER BY name DESC OFFSET (page-1)20 LIMIT 20` SELECT FROM history `ORDER BY name ASC,gender DESC OFFSET (page-1)*20 LIMIT 20`

状态码

描述	方法	说明	status
成功获取资源	GET	OK	200
成功创建或修改	POST,PUT,PATCH	CREATED	201
成功删除	DELETE	NO CONTENT	204
请求错误：GET参数问题；PUT提交数据错误	ALL	Bad Request	400
未认证	ALL	Unauthorized	401
认证通过，无权限	ALL	Forbidden	403
认证通过，找的资源不存在	ALL	Not Found	404
服务端	ALL	Internal Server Error	500

错误处理

单单从状态码无法详细描述错误信息

进程成功,状态码0，非0 有问题

消息

json
{
	"error": "User Not Found"
}

错误消息

json
{
	"code": 10056,
	"message": "Invalid ID",  # 简单的描述
	"description": "More details" # 详细的描述
}

大系统中，让用户给code，消息，描述。

版本

项目用的人越多，你不能随便修改。你需要升级项目，以便后续维护。

减少影响的方法

新接口新名称，旧接口，加参数，有默认值。
接口加版本信息

使用版本号，v2有2种风格

http://api.mykernel.cn/v1/posts -> http://api.mykernel.cn/v1/posts 前端和后端跨域了，内部加代理。大项目
http://www.mykernel.cn/api/v1/posts -> http://www.mykernel.cn/api/v1/posts 小项目

x.x.x 语义化版本, 发布时最终品才加x.x.x 而URL就大版本，小版本是兼容的。

第1个是大版本，不兼容
第2个是功能版本，兼容
第3个是补丁修复

返回结果

方法	路径	状态	描述
GET	/posts	200	返回所有文章列表或JS的数组
GET	/posts/10	200	返回id=10的文章对象
POST	/posts	201	创建新的文章并返回这个新创建的对象
PUT	/posts/10	201	更新id=10的文章，并返回这个被更新的对象
PATCH	/posts/10	201	部分更新id=10的文章，并返回这个被更新的对象
DELETE	/posts/10	204	删除id=10的文章返回一个空对象, 或不返回任何对象

目录