RESTful 设计理论

川长思鸟来 2021-11-17 13:00 249阅读 0赞

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

转载于:https://www.cnblogs.com/DONET-LC/p/Restful.html