为了前后端分工明确,对接流畅,确保可读性和扩展性以及高可用、一致性,特约定下述无状态RESTful API规范:
前后端分离意味着,前后端之间使⽤ JSON 来交流,两个开发团队之间使⽤ API 作为契约进⾏交互。从此,后台选⽤的技术栈不影响前台。当我们决定需要前后端分离时,我们仍然还需要⾯对⼀系列的问题:
前后端分离的核⼼:后台提供数据,前端负责显⽰
RESTful API 统一约束客户端和服务器之间的接口。简化和分离系统架构,使每个模块独立!
Content-Type: application/json; charset=utf-8
REST即表述性状态传递(英文:Representational State Transfer,简称REST)是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。它是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。**REST是设计风格而不是标准。**REST通常基于使用HTTP,URI,和XML(标准通用标记语言下的一个子集)以及HTML(标准通用标记语言下的一个应用)
统一接口约束定义客户端和服务器之间的接口。它简化了分离的结构,使各部分独立发展。
REST要求状态要么被放入资源状态中,要么保存在客户端上。或者换句话说,服务器端不能保持除了单次请求之外的,任何与其通信的客户端的通信状态。从客户端的每个请求要包含服务器所需要的所有信息。这样做的最直接的理由就是可伸缩性—— 如果服务器需要保持客户端状态,那么大量的客户端交互会严重影响服务器的内存可用空间(footprint)。
服务器返回信息必须被标记是否可以缓存,如果缓存,客户端可能会重用之前的信息发送请求。
客户端无需关注数据存储,服务器端无需关注用户界面,提高了前后端可移植性。
客户端不关心直接连接到最终服务器还是连接到中间服务器。中间服务器可以通过启用负载平衡和提供共享缓存来提高系统可扩展性。分层系统也可以执行安全策略。
服务器可以通过传输逻辑来临时扩展或定制客户端的功能。
GET https//domain.com/api/{模块名}/{?菜单名}/{接口名}/:param
请求方法 | 说明 | 安全性 | 幂等性 |
---|---|---|---|
GET(SELECT) | 获取资源 | ✔️ | ✔️ |
POST(CREATE) | 创建资源 | ❌ | ❌ |
PUT(UPDATE) | 更新资源 | ❌ | ✔️ |
DELETE(DELETE) | 删除资源 | ❌ | ✔️ |
说明:
被用于获取资源。不允许对服务器上资源做任何修改操作。
示例:
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample
常用于更新资源。通过请求体携带资源发送给服务器。注意:在资源ID由客户端而不是由服务器选择的情况下,也可以使用PUT来创建资源。修改成功返回200,创建成功返回201。建议使用post进行创建新资源。
PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff
常用于创建新资源。创建成功通常返回201。
POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders
删除资源。
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/buckets/sample
HTTP Verb | /customers | /customers/{id} |
---|---|---|
GET | 200 (OK),customers列表。 可用于分页、排序、过滤。 | 200 (OK),单个customer。如果id不存在或非法,返回404 (NotFound)。 |
PUT | 404 (Not Found),除非你想更新整个资源 | 200 (OK) 或者204 (No Content)。如果id不存在或非法,返回404 (NotFound)。 |
POST | 201 (Created) | 404 (Not Found) |
DELETE | 404 (Not Found),除非你想删除整个资源 | 200 (OK) 。如果id不存在或非法,返回404 (NotFound)。 |
-
表示降序,无任何标识表示升序。 sorts: ['-age', 'name']
状态码 | 说明 |
---|---|
200 OK | 服务器成功返回请求的数据 |
201 CREATED | 新建或修改数据成功 |
202 Accepted | 表示一个请求已经进入后台排队(异步任务) |
204 NO CONTENT | 删除数据成功 |
400 INVALID REQUEST | 请求有错误,服务器没有进行新建或修改数据的操作(幂等操作) |
401 Unauthorized | 没有权限(令牌、用户名、密码错误) |
403 Forbidden | 得到授权(与401错误相对),但是访问是被禁止的 |
404 NOT FOUND | 请求记录不存在,服务器没有进行操作(幂等操作) |
406 Not Acceptable | 请求的格式不符合(比如用户请求JSON格式,但是只有XML格式) |
500 INTERNAL SERVER ERROR | 服务器发生错误,无法判断发出的请求是否成功 |
{
"code": "200", // HTTP响应码(好多javascript框架并不会获取http状态码,所以包装到body中便于使用)
"status": "success/fail/error", // 见下述表格
"content/data": []/{}, // 多条记录使用JSON数组,单条记录使用JSON对象
"message": [] // 状态为error或fail时,对应的错误信息
}
status说明
状态 | 说明 |
---|---|
fail | 返回码为 500-599 |
error | 返回码为 400-499 |
success | 其他状态码(1xx、2xx、3xx) |
GET http://xxx.com/api/dashboard/se-count/:uid
{
"status": "success",
"content": [
{
"key": "low", // 前后端交互使用关键字
"name": "低级", // 前端显示
"value": 540
},
{
"key": "medium",
"name": "中级",
"value": 336
},
{
"key": "high",
"name": "高级",
"value": 92
}
],
errorCode: "",
message: ""
}
多条曲线
{
"status": "success",
"content":[
{
"key": "firewall",
"name": "Firewall",
"value": [
{
"key": 1508083200000,
"name": "3:00",
"value": 23
},
{
"key": 1508094000000,
"name": "6:00",
"value": 43
}
]
},
{
"key": "V**",
"name": "V**",
"value": [
{
"key": 1508083200000,
"name": "3:00",
"value": 31
},
{
"key": 1508094000000,
"name": "6:00",
"value": 33
}
]
}
]
}
请求
POST http://xxx.com/api/dashboard/se-by-source-ip
{
startTime: 1505977365777,
endTime: 1506063765777,
pageNum: 1, // 当前页码
pageSize: 20, // 每页条数
}
响应结果
{
"total": 1, // 总条数
"totalPage": 1, // (可选)总页数
"pageNum": 1, // (可选)当前页码
"pageSize": 20, // (可选)每页条数
"value": [
{
"field1": "value",
"field2": "value",
"field3": "value",
"field4": "value"
}
]
}
参照文档:http://vdisk.weibo.com/s/qO04zNmE2310