RESTful 设计理论

Posted 2021-11-29 donet-lc

RESTful 设计：

1.协议
通信协议：https

2.域名
部署在API专用域名下，除非API很简单（https://www.example.com/api）
https://api.example.com

 

3.版本
应将版本号放在url中（.../v1/...）;也可以放在http头中

 

4.路径
不能有动词，只能有名词；所用名词常和数据库表格名对应
（ps:https://api.example.com/v1/users）

 

5.HTTP动词
GET(SELECT)：获取一个或多个 eg: /users /users/id /users/id/hobbys
POST(CREATE):新增 eg: /users
PUT(UPDATE):更新整个对象 eg: /users/id
PATCH(UPDATE):更新部分属性 eg: /users/id
DELETE(DELETE):删除 eg: /users/id /users/id/hobbys/id

HEAD:获取元数据
OPTIONS:获取可以修改的属性

6.过滤信息（类似分页）
?limit=10 条数
?offset=10 开始位置
?page=2&per_page=100 分页
?sortby=name&order=ase 属性排序、排序规则
?name=aaa 添加筛选条件

7.常见状态码（Status Codes）
200 OK 幂等操作
201 CREATED - (post/put/patch) 用户新增或修改成功
202 Accepted - (*) 表示已进入后台排队（异步任务）
204 NO CONTENT - [delete] 删除数据成功
400 Invalid request - (post/put/patch) 请求有误，没有进行修改操作，幂等操作
401 Unauthorized - (*) 没有权限
403 Forbidden - (*) 有权限，但被禁止访问
404 Not Found - (*) 不存在的资源，幂等操作
406 Not Accepted - (get) 请求参数格式错误
410 Gone - (get) 资料被删除，且不会再得到
422 Unprocesable entity - (get/put/patch) 创建对象，发生验证错误
500 Internal server error - (*) 服务器发生错误，无法判断请求是否成功

8.错误处理
状态码为4xx，返回error信息 ：{ error:"Invalid is fail"}

9.返回结果
GET： /users   返回列表      /users/id 返回单个对象
POST: /users   返回新增对象
PUT: /users/id  返回整个对象
PATCH： /users/id  返回完整对象
DELETE: /users/id  返回空文档

10.Hypermedia API
向api.example.com根目录发送请求，返回一个文档
{
"user_url":"https://api.example.com/user",
//...
}
向子目录发送请求，返回单个说明文档：
{
"documentation_url":"https://api.example.com/v1/users",
"message":"user infomation"
}

11.其它
1.api的身份认证应该使用OAuth 2.0 框架
2.数据格式尽量用JSON