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=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
}