Restful规范
【感谢我的好同事小白同学的分享】我只是个备份搬运工。
概述
采用http接口，使用RESTful规范
通用信息
版本控制
默认返回最新的版本API，可以通过显式在header中指定
Accept: application/vnd.apollo.v1+json时间格式
所有的时间返回使用ISO 8601格式，如下：
YYYY-MM-DDTHH:MM:SSZ错误信息
API返回的http status为40x或是50x，返回的JSON中，含有detail字段（可为空）
HTTP/1.1 400 Bad Request
Content-Length: 34
{"detail":"Problems parsing JSON"}HTTP方法
| Verb | Description |
|---|---|
| HEAD | 与GET不同之处在于，只获得header信息 |
| GET | 获取资源，幂等 |
| POST | 创建资源，非幂等 |
| PUT | 全量更新资源，幂等 |
| PATCH | 部分更新资源，非幂等（有争议） |
| DELETE | 删除资源，非幂等 |
Authentication
当用户未登录而访问需要登录的资源时，返回401，而登录用户由于权限问题，无法访问资源时，返回403。
HTTP标准建议，对于401的请求，必须携带WWW-Authenticate头，来告知客户端该如何进行认证。
对于Basic的认证，由于浏览器会捕获该请求，然后做Alert框处理，如过不需要该功能，可以将默认的Basic认证改为其他自定义认证方式，如LDAP。
分页
如果接口支持分页显示，则在query parameters中加入page参数，也可以加入limit参数(可选)，当page为空时，默认为1，page小于1，则为1。
GET /api/resources?page=2&limit=100Nested Resource
当遇到资源录属于其他资源时，针对此类URL，可以使用如下方式构造（可选）。
list url: /api/resources/:resource_id/sub_resourcesdetail url: /api/sub_resources/:id (shallow模式)针对detail url，也可以采用如下的方式：
detail url: /api/resources/:resource_id/sub_resources/:id但如采用上一种形式，需要处理，当sub_resource id不属于resource_id时，显示返回约定好的code(400?404?)。 因此建议采用shallow模式。
dbs
List dbs
列出所有在该用户权限下的DB列表
GET /api/dbsResponse
Status: 200 OK
[
{
"id": 1,
"instance_id": 1002,
"name": "apollo",
"alias_name": "apollo"
}
]Get a single db
获取一个DB的详细信息
GET /api/dbs/:idResponse
Status: 200 OK
[
{
"id": 1,
"instance_id": 1002,
"name": "apollo",
"alias_name": "apollo",
"tables": [
{
"id": 1,
"name": "auth_user",
"comment": "User Table"
}
]
}
]Get a single table
获取一个Table的详细信息
GET /api/tables/:idResponse
Status: 200 OK
[
{
"id": 1,
"name": "auth_user",
"comment": "User Table",
"columns": [
{
"id": 1,
"name": "id",
"ordinal_position": 1,
"column_defaul": null,
"is_nullable": "NO"
}
],
"indexes": [
{
"id": 1,
"name": "PRIMARY",
"non_unique": 0,
"seq_in_index": 1,
"column_name": "id",
"created_at": "2017-05-13T13:46:33Z",
"modified_at": "2017-05-13T13:46:33Z"
}
]
}
]工单
工单列表
获取登陆用户的工单，包括被指派的，自己创建的工单，可以通过filter参数控制，由于允许分页，返回的数据中需要分页信息。
GET /api/tickesParameters
| Name | Type | Description |
|---|---|---|
| filter | string | assigned: 被指派的 created: 自己创建的 all: 包含以上 默认为all |
| state | string | open, closed 或是 all，默认为all |
Response
Status: 200 OK
{
"count": 1,
"results": [
{
"id": 1,
"title": "ticket title",
"description": "ticket description",
"status": "open",
"created_at": "2017-05-13T13:46:33Z",
"updated_at": "2017-05-13T13:46:33Z",
"is_expired": null,
"initiator": {
"id": 1,
"username": "user name"
},
"assignee": {
"id": 2,
"username": "user name"
}
}
]
}工单详情
获取工单的详细信息
GET /api/tickets/:idResponse
Status: 200 OK
{
"id": 1,
"title": "ticket title",
"description": "ticket description",
"status": "closed",
"created_at": "2017-05-13T13:46:33Z",
"updated_at": "2017-05-13T13:46:33Z",
"is_expired": null,
"initiator": {
"id": 1,
"username": "user name"
},
"assignee": {
"id": 1,
"username": "user name"
},
"actions": [
{
"id": 1,
"action_type": "close",
"comment": "action comment",
"created_at": "2017-05-13T13:46:33Z",
"updated_at": "2017-05-13T13:46:33Z",
"operator": {
"id": 3,
"username": "user name"
}
}
]
}通知列表
获取通知的列表信息，由于在应用中，不需要显示分页，而是使用下拉刷新的形式，因此，返回的数据不需要添加分页信息。
在返回的数据中，由于related_object是根据不同的notification_type而会有不同的对象类型，需要独立判断处理。
GET /api/notificationsResponse
Status: 200 OK
{
"id": 1,
"notification_type": 1,
"read": true,
"created_at": "2017-05-13T13:46:33Z",
"updated_at": "2017-05-13T13:46:33Z",
"actors": [
{
"id": 1,
"username": "user name"
}
],
"recipient": {
"id": 2,
"username": "recipient name"
},
"related_object": {
"id": 1,
"state": "open",
"ticket_type": 1,
"title": "ticket title"
}
}通知数量
获取该用户的全部和未读通知的数量。
GET /api/notifications/amountResponse
Status: 200 OK
{
"count": 100,
"unread": 50
}更新通知数量
更新用户的通知数量，可用于标记通知全部已读。
PUT /api/notifications/amountResponse
Status: 200 OK
{
"count": 100,
"unread": 0
}