Restful API设计学习总结
什么是 Restful API
?
RESTful API
是目前比较成熟的一套互联网应用程序的API设计理论.
关注点 | 说明 |
---|---|
协议 | http / https |
域名 | api.domain.com / domain.com/api/ |
版本 | api.domain.com/v1/ / 在 Request Header 中加入版本信息 |
设计步骤
第一步 、资源路径
一切均资源。所以,不能使用动词,一般都是用名词复数形式。如:
users
,posts
.
第二步、HTTP动词的确定
动词 | 说明 |
---|---|
GET | 读取,取出资源 |
POST | 新建资源 |
PUT | 更新资源(全部修改) |
PATCH | 更新资源(部分修改) |
DELETE | 删除资源 |
第三步、过滤信息的设计
过滤 | 解释 |
---|---|
?limit=10 | 限制条数 |
?offset=10 | 指定读取位置 |
?page=1&per_page=20&sortBy=created_at&order=desc | 分页信息 |
other | 其他过滤信息 |
第四步、HTTP状态码
状态码 | 解释 | 说明 |
---|---|---|
200 | OK | GET请求成功 |
201 | CREATED | 资源创建成功或编辑成功 |
202 | Accepted | 资源处理已添加入队列 |
204 | NO CONTENT | 删除成功 |
400 | INVALID REQUEST | 用户请求错误(POST,PUT,PATCH) |
401 | Unauthorized | 无权限 |
403 | Forbidden | 操作被禁止 |
404 | NOT FOUND | 记录不存在 |
406 | Not Acceptable | 用户请求的数据格式错误 |
422 | Unprocesable entity | 创建或编辑对象时未通过验证,如:用户名长度不符合 |
500 | INTERNAL SERVER ERROR | 服务器内部错误 |
第五步、错误处理
如果状态码是4xx信息,需要返回错误信息
JSON
格式数据,如:
{
"error": "error information."
}
第六步、注意事项
- 返回数据尽量使用
JSON
数据格式,避免使用XML
. - 用户授权采用
OAuth 2.0
协议.
实例
现在以 post
做个实例.以下是 RESTful API
设计:
版本,协议,域名不考虑.
URL | Method | 说明 | 可以返回的状态码 |
---|---|---|---|
/posts?{page=1&per_page=10&limit=10&offset=10} | GET | 获取部分(所有)帖子 | 200,404 |
/post/1 | GET | 获取ID为1的帖子 | 200,404 |
/post | POST | 创建帖子 | 201,202,400,401,403,406,422,500 |
/post/1 | DELETE | 删除ID为1的帖子 | 204,401,403,404,500 |
/post/1 | PUT | 编辑ID为1的帖子 | 201,202,400,401,403,406,422,500 |
项目实战
本作品采用 知识共享署名-相同方式共享 4.0 国际许可协议 进行许可。
评论已关闭