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.前后端不分离 在前后端不分离的应用模式中,前端页面看到的效果都是由后端控制,由后端渲染页面或重定向,也就是后端需要控制前端的展示,前端与后端的耦合度很高. 这种应用模式比 ...
随机推荐
- H5页面遮罩弹框下层还能滚动的问题
在页面上显示一个遮罩层,这是非常常见的操作,在遮罩层上操作,下层也会默认跟随手指滚动 此处就是要在显示遮罩的时候禁止下层滚动. 首先设置一个全局变量 var canScroll=false; 页面初始 ...
- BZOJ 1898: [Zjoi2005]Swamp 沼泽鳄鱼
1898: [Zjoi2005]Swamp 沼泽鳄鱼 Time Limit: 5 Sec Memory Limit: 64 MBSubmit: 1085 Solved: 604[Submit][S ...
- Java之字节数组和字符串的转换问题
今天在使用字节流复制图片的时候发现一个问题,就是将字节数组转化为字符串的时候会出现长度不同的问题.这其实是个错误的操作. public static void main(String[] args) ...
- Android 资源目录 相关知识 raw、 drawable、 values..
一定要看的 Android 资源目录的相关知识 raw drwable valueshttp://blog.csdn.net/shichexixi/article/details/5985677 ht ...
- Android自定义 Dialog 对话框
Android自定义Dialoghttp://www.cnblogs.com/and_he/archive/2011/09/16/2178716.html Android使用自定义AlertDialo ...
- kernel-init-bash
https://www.kernel.org/doc/Documentation/kernel-parameters.txthttp://unix.stackexchange.com/question ...
- 题解【bzoj1503 [NOI2004]郁闷的出纳员】
Description 给出一个下限 \(m\) ,要求维护以下操作 插入一个数(如果小于下限就不加) 给每个数加上一个数 给每个数减去一个数,并且删除掉 \(< m\) 的所有数 求目前第 \ ...
- tp 用group去重
$baseGoodIds_arr = [1,2,3,4,5,6,7,8,9];$relate_gimgs = D('GoodsImages')->where(['good_id' => [ ...
- linux命令总结之ip命令
Linux的ip命令和ifconfig类似,但前者功能更强大,并旨在取代后者.使用ip命令,只需一个命令,你就能很轻松地执行一些网络管理任务.ifconfig是net-tools中已被废弃使用的一个命 ...
- in的对象选择(子查询还是List集合),in 的优化,in与exists
近日查看SQL慢查询日志,发现对于in的查询总是出现超时问题.超时相关SQL语句:select * from flow_ru_bizvar where businessId IN () and sta ...