restful API 规范(转)
1. URI
URI 表示资源,资源一般对应服务器端领域模型中的实体类。
URI规范
- 不用大写;
- 用中杠
-
不用下杠_
; - 参数列表要encode;
- URI中的名词表示资源集合,使用复数形式。
资源集合 vs 单个资源
URI表示资源的两种方式:资源集合、单个资源。
资源集合:
/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物
单个资源:
/zoos/1 //id为1的动物园
避免层级过深的URI
/
在url中表达层级,用于按实体关联关系进行对象导航,一般根据id导航。
过深的导航容易导致url膨胀,不易维护,如 GET /zoos/1/areas/3/animals/4(超过3层算过深)
,尽量使用查询参数代替路径中的实体导航,如GET /animals?zoo=1&area=3
;
对Composite资源的访问
服务器端的组合实体必须在uri中通过父实体的id导航访问。
组合实体不是first-class的实体,它的生命周期完全依赖父实体,无法独立存在,在实现上通常是对数据库表中某些列的抽象,不直接对应表,也无id。一个常见的例子是 User — Address,Address是对User表中zipCode/country/city三个字段的简单抽象,无法独立于User存在。必须通过User索引到Address:
GET /user/1/addresses
Action不符合CRUD操作
利用RESTful原则像处理子资源一样处理它。例如,Github的API让你通过PUT /gists/:id/star 来 star a gist ,而通过DELETE /gists/:id/star来进行 unstar 。
我们统一用post操作,在url的最后增加操作,以上面Github的例子来说,分别为POST /gits/:id/star,POST /gits/:id/unstar
2. Request
HTTP方法
通过标准HTTP方法对资源CRUD:
GET:查询
GET /zoos
GET /zoos/1
GET /zoos/1/employees
POST:创建单个资源。POST一般向“资源集合”型uri发起
POST /animals //新增动物
POST /zoos/1/employees //为id为1的动物园雇佣员工
PUT:更新单个资源(全量),客户端提供完整的更新后的资源。与之对应的是 PATCH,PATCH 负责部分更新,客户端提供要更新的那些字段。PUT/PATCH一般向“单个资源”型uri发起
PUT /animals/1
PUT /zoos/
我们用post和在url上加了“create”代替PUT,如:post: schools/create, post: schools/:id/update
DELETE:删除
DELETE /zoos/1/employees/2
DELETE /zoos/1/employees/2;4;5
DELETE /zoos/1/animals //删除id为1的动物园内的所有动物
我们用post和在url上加了“remove/delete”代替DELETE, 如: post: schools/:id/remove
如果参数超过url长度限制,可以使用post代替
安全性和幂等性
- 安全性:不会改变资源状态,可以理解为只读的;
- 幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。
GET | √ | √ |
POST | × | × |
PUT | × | √ |
DELETE | × | √ |
安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。
幂等性参考:http://www.cnblogs.com/weidagang2046/archive/2011/06/04/2063696.html
复杂查询
查询可以捎带以下参数:
过滤条件 | ?type=1&age=16 |
允许一定的uri冗余,如/zoos/1 与/zoos?id=1 |
排序 | ?sort=age,desc |
|
投影 | ?whitelist=id,name,email |
|
分页 | ?pageSize=10&pageNum=3 |
|
搜索 | ?k=关键字1 | k表示key,关键字 |
Bookmarker
经常使用的、复杂的查询标签化,降低维护成本。
如:
GET /trades?status=closed&sort=created,desc
快捷方式:
GET /trades#recently-closed
或者
GET /trades/recently-closed
Format
只用以下常见的3种body format:
Content-Type: application/json
POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24 {
"name": "Gir",
"animalType": "12"
}Content-Type: application/x-www-form-urlencoded (浏览器POST表单用的格式)
POST /login HTTP/1.1
Host: example.com
Content-Length: 31
Accept: text/html
Content-Type: application/x-www-form-urlencoded "username":"root""password":"Zion0101"(MD5加密)
- Content-Type: multipart/form-data; boundary=—-RANDOM_jDMUxq4Ot5 (表单有文件上传时的格式)
Content Negotiation
资源可以有多种表示方式,如json、xml、pdf、excel等等,客户端可以指定自己期望的格式,通常有两种方式:
http header
Accept
:Accept:application/xml;q=0.6,application/atom+xml;q=1.0
q为各项格式的偏好程度
- url中加文件后缀:
/zoo/1.json
6. Response
不要包装:
response 的 body 直接就是数据,不要做多余的包装,示例:{
"code":10000,
"data":{"id":1,"name":"xiaotuan"}
}失败样例:
{
"code":10103,
"message":""
}各HTTP方法成功处理后的数据格式:
GET 单个对象、集合 POST 新增成功的对象 PUT/PATCH 更新成功的对象 DELETE 空 json格式的约定:
- 时间用长整形(毫秒数),客户端自己按需解析(moment.js)
- 不传
null
字段
分页response
{
"code":10000
"data":{
"pageNum": 3,
"pageSize": 10,
"totalCount": 100,
"totalPage": 10,
"items":[{},{},{}...]
}
}
7. 错误处理
- 不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;
- 正确设置http状态码,不要自定义;
- Response body 提供 1) 错误的代码(日志/问题追查);2) 错误的描述文本(展示给用户)。
对第三点的实现稍微多说一点:
Java 服务器端一般用异常表示 RESTful API 的错误。API 可能抛出两类异常:业务异常和非业务异常。业务异常由自己的业务代码抛出,表示一个用例的前置条件不满足、业务规则冲突等,比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题,通常由类库、框架抛出,或由于自己的代码逻辑错误导致,比如数据库连接失败、空指针异常、除0错误等等。
业务类异常必须提供2种信息:
- 如果抛出该类异常,HTTP 响应状态码应该设成什么;
- 异常的文本描述;
在Controller层使用统一的异常拦截器:
- 设置 HTTP 响应状态码;
- Response Body 的错误码:对业务类异常,用自定义的其他状态码;对非业务类异常,统一用10103
- Response Body 的错误描述:对业务类异常,用它指定的错误文本;对非业务类异常,线上可以统一文案如“服务器端错误,请稍后再试”,开发或测试环境中用异常的 stacktrace,服务器端提供该行为的开关。
常用的http状态码及使用场景(这里我们统一返回200,在消息体中使用自定义的状态码来处理):
400 bad request | 常用在参数校验 |
401 unauthorized | 未经验证的用户,常见于未登录。如果经过验证后依然没权限,应该 403(即 authentication 和 authorization 的区别)。 |
403 forbidden | 无权限 |
404 not found | 资源不存在 |
500 internal server error | 非业务类异常 |
503 service unavaliable | 由容器抛出,自己的代码不要抛这个异常 |
8. 服务型资源
除了资源简单的CRUD,服务器端经常还会提供其他服务,这些服务无法直接用上面提到的URI映射。如:
- 按关键字搜索;
- 计算地球上两点间的距离;
- 批量向用户推送消息
可以把这些服务看成资源,计算的结果是资源的presentation,按服务属性选择合适的HTTP方法。
例:
GET /search?q=filter?category=file 搜索
GET /distance-calc?lats=47.480&lngs=-122.389&late=37.108&lnge=-122.448
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]
9. 异步任务
对耗时的异步任务,服务器端接受客户端传递的参数后,应返回创建成功的任务资源,其中包含了任务的执行状态。客户端可以轮训该任务获得最新的执行进度。
提交任务:
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]
返回:
{"taskId":3,"createBy":"Anonymous","status":"running"}
GET /task/3
{"taskId":3,"createBy":"Anonymous","status":"success"}
如果任务的执行状态包括较多信息,可以把“执行状态”抽象成组合资源,客户端查询该状态资源了解任务的执行情况。
提交任务:
POST /batch-publish-msg
[{"from":0,"to":1,"text":"abc"},{},{}...]
返回:
{"taskId":3,"createBy":"Anonymous"}
GET /task/3/status
{"progress":"50%","total":18,"success":8,"fail":1}
10. API的演进
版本
常见的三种方式:
- 在uri中放版本信息:
GET /v1/users/1
- Accept Header:
Accept: application/json+v1
- 自定义 Header:
X-Api-Version: 1
- 在uri中放版本信息:
用第一种,虽然没有那么优雅,但最明显最方便。
URI失效
随着系统发展,总有一些API失效或者迁移,对失效的API,返回404 not found 或 410 gone;对迁移的API,返回 301 重定向。
参考内容:https://github.com/aisuhua/restful-api-design-references
restful API 规范(转)的更多相关文章
- day71:drf:API接口&Restful API规范&Django Rest Framework&drf中的序列化和反序列化功能
目录 1.web应用模式 2.API接口 3.Restful API规范 4.序列化 5.Django Rest Framework 1.drf的简单介绍 2.drf的特点 3.如何安装drf 4.d ...
- RESTful API规范
1. 域名 应该尽量将API部署在专用的域名下. https://api.example.com 如果确定API简单,不会有进一步的括在,可以考虑放在主域名之下. https://example.or ...
- RESTful API 规范(一)
一,简介 DRF 即Django rest framework 二,rest 规范 1 协议 API 与用户通信,总是使用https协议 2 域名 1) 应尽量将API 部署在域名下(这种情况会存在跨 ...
- 初识 RESTful API规范
简介 一种软件架构风格.设计风格,而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. rest是一种 ...
- restful api 规范
- 后端api规范说明文档
我们此次后端api的实现主要是按照RESTful api规范来设计的,就是符合REST架构下设计api的规范.简单的来说REST结构就是:利用URL定位资源,用HTTP动词(GET,POST,PUT, ...
- 理解Restful api的意义
RESTful API 只是API的设计规范或者是一套设计理论. 单就URL和Method这两个点,你可以这样理解: URL 是用来唯一标示一个互联网资源的,而 Method 是用来标识当前请求对该资 ...
- Restful Api CRUD 标准示例 (Swagger2+validator)
为什么要写这篇贴? 要写一个最简单的CRUD 符合 Restful Api 规范的 一个Controller, 想百度搜索一下 直接复制拷贝 简单修改一下 方法内代码. 然而, 搜索结果让我无 ...
- 前后端分离和restful开发规范
一.web开发的两种模式 1.前后端不分离 在前后端不分离的应用模式中,前端页面看到的效果都是由后端控制,由后端渲染页面或重定向,也就是后端需要控制前端的展示,前端与后端的耦合度很高. 这种应用模式比 ...
随机推荐
- Vue 中使用UEditor富文本编辑器-亲测可用-vue-ueditor-wrap
其中UEditor中也存在不少错误,再引用过程中. 但是UEditor相对还是比较好用的一个富文本编辑器. vue-ueditor-wrap说明 Vue + UEditor + v-model 双向绑 ...
- 导入eclipse工程到Android Studio中
ref:从 Eclipse 迁移至 Android Studio | Android Studiohttps://developer.android.com/studio/intro/migrate. ...
- AS可视化布局中文乱码
求助android studio 的可视化布局中文乱码-CSDN论坛-CSDN.NET-中国最大的IT技术社区http://bbs.csdn.net/topics/391887442 Android ...
- JavaScript演示下Singleton设计模式
单例模式的基本结构: MyNamespace.Singleton = function() { return {}; }(); 比如: MyNamespace.Singleton = (functio ...
- 数据融合(data fusion)原理与方法
数据融合(data fusion)原理与方法 数据融合(data fusion)最早被应用于军事领域. 现在数据融合的主要应用领域有:多源影像复合.机器人和智能仪器系统.战场和无人驾驶飞机.图 ...
- 2018-2019 ACM-ICPC ECfinal I. Misunderstood … Missing
题目链接 首先有两个个属性值:\(A,D\),其中\(A\)表示目前攻击力,\(D\)表示每回合攻击的增量. 现在一共有\(n\)个回合,每一回合\(i\),可以有以下三种操作: 1.进行攻击,造成\ ...
- centos systemctl daemon-reload 提示 no such file or directory 的一个原因
service 的文件名写错了 比如 mongodb.service 写成了 mongodb.srvice 真的是坑,居然没有提示具体的路径,只是提示一个 no such file or direct ...
- 个人常用Linux文件操作命令
本文只记录个人工作中最常用到的命令. 关机和用户 shutdown -h now 关机 reboot 重启 sync 非正常关机前执行,强制将内存缓冲区中的数据立即写入磁盘中 logout 注销 ...
- [Java] I/O底层原理之一:字符流、字节流及其源码分析
关于 I/O 的类可以分为四种: 关于字节的操作:InputStream 和 OutPutStream: 关于字符的操作:Writer 和 Reader: 关于磁盘的操作:File: 关于网络的操作: ...
- SQL Server 属性不匹配。存在属性(Directory, Archive),包括属性(0),不包括属性(Archive, Compressed, Encrypted)
问题:安装SQL SERVER 2008报错 “存在属性(Directory, Archive),包括属性(0),不包括属性(Archive, Compressed, Encrypted)” 解决办法 ...