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 RequestContent-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=100

Nested Resource

当遇到资源录属于其他资源时，针对此类URL，可以使用如下方式构造（可选）。

list url: /api/resources/:resource_id/sub_resources

detail 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/dbs

Response

Status: 200 OK[  {    "id": 1,    "instance_id": 1002,    "name": "apollo",    "alias_name": "apollo"  }]

Get a single db

获取一个DB的详细信息

GET /api/dbs/:id

Response

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/:id

Response

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/tickes

Parameters

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/:id

Response

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/notifications

Response

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/amount

Response

Status: 200 OK{  "count": 100,  "unread": 50}

更新通知数量

更新用户的通知数量，可用于标记通知全部已读。

PUT /api/notifications/amount

Response

Status: 200 OK{  "count": 100,  "unread": 0}