API 参考

API 参考

1. 端点

1.1 应用

列出应用

- Method: GET- Endpoint: /apps- Format: JSON

成功时返回 200，在响应的 body 中的 JSON 数据包含了应用列表。

例子：

GET /apps HTTP/1.1
Content-Length: 82
[{"Ip":"10.10.10.10","Name":"app1","Units":[{"Name":"app1/0","State":"started"}]}]

应用的信息

- Method: GET- Endpoint: /apps/- Format: JSON

成功时返回 200，在响应的 body 中的 JSON 数据包含了应用的内容。

例子：

GET /apps/myapp HTTP/1.1
Content-Length: 284
{"Name":"app1","Framework":"php","Repository":"git@git.com:php.git","State":"dead","Units":[{"Ip":"10.10.10.10","Name":"app1/0","State":"started"}, {"Ip":"9.9.9.9","Name":"app1/1","State":"started"},{"Ip":"","Name":"app1/2","State":"pending"}],"Teams":["tsuruteam","crane"],"Pool": "mypool"}

删除一个应用

- Method: DELETE- Endpoint: /apps/

成功时返回 200。

例子：

DELETE /apps/myapp HTTP/1.1

创建一个应用

- Method: POST- Endpoint: /apps- Format: JSON

成功时返回 200，在响应的 body 中的 JSON 数据包含了状态和 Git 仓库的 URL 。

例子：

POST /apps HTTP/1.1
{"status":"success", "repository_url":"git@tsuru.mycompany.com:ble.git"}

重启一个应用

- Method: GET- Endpoint: /apps//restart

成功时返回 200。

例子：

GET /apps/myapp/restart HTTP/1.1

给应用环境变量

- Method: GET- Endpoint: /apps//env

成功时返回 200，在响应的 body 中的 JSON 数据返回了一个带环境名和值的字典。

例子：

GET /apps/myapp/env HTTP/1.1
[{"name": "DATABASE_HOST", "value": "localhost", "public": true}]

设置一个应用环境

- Method: POST- Endpoint: /apps//env

成功时返回 200。

例子：

POST /apps/myapp/env HTTP/1.1

执行一个命令

- Method: POST- Endpoint: /apps//run?once=true

成功时返回 200。

此处:

• once 是一 boolean 值，指示命令是在一个单元上运行(once=true)还是在所有单元上运行(once=false)。这一参数不是必须的，缺省值为 false。
  例子：

POST /apps/myapp/run HTTP/1.1
ls -la

从一个应用中删除一个或多个环境变量

- Method: DELETE- Endpoint: /apps//env

成功时返回 200。

例子：

DELETE /apps/myapp/env HTTP/1.1

交换两个应用的地址

- Method: PUT- Endpoint: /swap?app1=appname&app2=anotherapp

成功时返回 200。

例子：

PUT /swap?app1=myapp&app2=anotherapp

获取一个应用的日志

- Method: GET- Endpoint: /apps/appname/log?lines=10&source=web&unit=abc123

成功时返回 200。找不到应用时返回 404。

此处:

• lines 是日志行数。这一参数是必须的。
• source 是日志源，如 tsuru (tsuru API) 或一个进程。
• unit 是一个单元的 id 。
  例子：

GET /apps/myapp/log?lines=20&source=web&unit=83535b503c96
Content-Length: 142
[{"Date":"2014-09-26T00:26:30.036Z","Message":"Booting worker with pid: 53","Source":"web","AppName":"tsuru-dashboard","Unit":"83535b503c96"}]

列出可用的池子（pool）

- Method: GET- Endpoint: /pools

成功时返回 200。

例子：

GET /pools
[{"Team":"team1","Pools":["pool1","pool2"]},{"Team":"team2","Pools":["pool3"]}]

改变应用的池子（pool）

- Method: POST- Endpoint: /apps//pool

成功时返回 200。找不到应用时返回 404。

例子：

POST /apps/myapp/pool

1.2 服务

列出服务

- Method: GET- Endpoint: /services- Format: JSON

成功时返回 200。

例子：

GET /services HTTP/1.1
Content-Length: 67
{"service": "mongodb", "instances": ["my_nosql", "other-instance"]}

创建一个新的服务

- Method: POST- Endpoint: /services- Format: yaml- Body: a yaml with the service metadata.

成功时返回 200。如果用户不是团队成员时返回 403。如果 yaml 非法时返回 500。如果服务名字已经存在时返回 500。

例子：

POST /services HTTP/1.1
id: some_service
endpoint:
  production: someservice.com

删除一个服务

- Method: DELETE- Endpoint: /services/

成功时返回 204。如果用户没有进入（access）服务器时返回 403。如果服务已经有实例时返回 403。服务找不到时返回 404。

例子：

DELETE /services/mongodb HTTP/1.1

更新一个服务

- Method: PUT- Endpoint: /services- Format: yaml- Body: a yaml with the service metadata.

成功时返回 200。如果用户不是团队成员时返回 403。如果 yaml 非法时返回 500。如果服务名字已经存在时返回 500。

例子：

PUT /services HTTP/1.1
id: some_service
endpoint:
  production: someservice.com

获取一个服务的信息

- Method: GET- Endpoint: /services/- Format: JSON

成功时返回 200。如果服务不存在时返回 404。

例子：

GET /services/mongodb HTTP/1.1
[{"Name": "my-mongo", "Teams": ["myteam"], "Apps": ["myapp"], "ServiceName": "mongodb"}]

获取服务文档

- Method: GET- Endpoint: /services//doc- Format: text

成功时返回 200。如果服务不存在时返回 404。

例子：

GET /services/mongodb/doc HTTP/1.1
Mongodb exports the ...

更新服务文档

- Method: PUT- Endpoint: /services//doc- Format: text- Body: text with the documentation

成功时返回 200。如果服务不存在时返回 404。

例子：

PUT /services/mongodb/doc HTTP/1.1
Body: Mongodb exports the ...

授予服务访问（权限）

- Method: PUT- Endpoint: /services//

成功时返回 200。如果服务不存在时返回 404。

例子：

PUT /services/mongodb/cobrateam HTTP/1.1

撤销服务的访问（权限）

- Method: DELETE- Endpoint: /services//

成功时返回 200。如果服务不存在时返回 404。

例子：

DELETE /services/mongodb/cobrateam HTTP/1.1

1.3 服务实例

增加一个新的服务实例

- Method: POST- Endpoint: /services/instances- Body: {"name": "mymysql", "service_name": "mysql"}

成功时返回 200。如果服务不存在时返回 404。

例子：

POST /services/instances HTTP/1.1
{"name": "mymysql", "service_name": "mysql"}

删除一个服务实例

- Method: DELETE- Endpoint: /services/instances/

成功时返回 200。如果服务不存在时返回 404。

例子：

DELETE /services/instances/mymysql HTTP/1.1

绑定一个服务实例到一个应用

- Method: PUT- Endpoint: /services/instances//- Format: JSON

成功时返回 200，以及一个将要导出到应用环境的环境变量的 JSON 数据。如果用户没有访问应用的权限时返回 403。如果应用不存在时返回 404。如果服务实例不存在时返回 404。

例子：

PUT /services/instances/mymysql/myapp HTTP/1.1
Content-Length: 29
{"DATABASE_HOST":"localhost"}

把一个服务实例从一个应用中解绑定

- Method: DELETE- Endpoint: /services/instances//

成功时返回 200。如果用户没有访问应用的权限时返回 403。如果应用不存在时返回 404。如果服务实例不存在时返回 404。

例子：

DELETE /services/instances/mymysql/myapp HTTP/1.1

列出所有的服务及你的实例

- Method: GET- Endpoint: /services/instances?app=appname- Format: JSON

成功时返回 200，以及一个服务列表的 JSON 数据。

此处:

• app 是你想用作过滤器的应用的名字。如果定义了，只有绑定到这个应用的实例才会返回。这一参数是可选的。
  例子：

GET /services/instances HTTP/1.1
Content-Length: 52
[{"service": "redis", "instances": ["redis-globo"]}]

获取一个服务实例的信息

- Method: GET- Endpoint: /services/instances/- Format: JSON

成功时返回 200，以及一个服务实例数据的 JSON 数据。如果服务实例不存在时返回 404。

例子：

GET /services/instances/mymysql HTTP/1.1
Content-Length: 71
{"name": "mongo-1", "servicename": "mongodb", "teams": [], "apps": []}

服务实例状态

- Method: GET- Endpoint: /services/instances//status

成功时返回 200。

例子：

GET /services/instances/mymysql/status HTTP/1.1

授予服务实例访问（权限）

- Method: PUT- Endpoint: /services/instances/permission//

成功时返回 200。如果服务不存在时返回 404。

例子：

PUT /services/instances/permission/mongodb-instance/cobrateam HTTP/1.1

撤销服务实例的访问（权限）

- Method: DELETE- Endpoint: /services/instances/permission//

成功时返回 200。如果服务不存在时返回 404。

例子：

DELETE /services/instances/permission/mongodb-instance/cobrateam HTTP/1.1

1.4 配额

获取一个用户的配额信息

- Method: GET- Endpoint: /quota/- Format: JSON

成功时返回 200，以及一个配额信息的 JSON 数据。

例子：

GET /quota/wolverine HTTP/1.1
Content-Length: 29
{"items": 10, "available": 2}

1.5 修复者（Healers）

列出修复者

- Method: GET- Endpoint: /healers- Format: JSON

成功时返回 200，以及一个 body 中的修复者列表的 JSON 数据。

例子：

GET /healers HTTP/1.1
Content-Length: 35
[{"app-heal": "http://healer.com"}]

执行修复者

- Method: GET- Endpoint: /healers/

成功时返回 200。

例子：

GET /healers/app-heal HTTP/1.1

1.6 平台

列出平台

- Method: GET- Endpoint: /platforms- Format: JSON

成功时返回 200，以及一个 body 中的平台列表的 JSON 数据。

例子：

GET /platforms HTTP/1.1
Content-Length: 67
[{Name: "python"},{Name: "java"},{Name: "ruby20"},{Name: "static"}]

1.7 用户

创建一个用户

- Method: POST- Endpoint: /users- Body: {"email":"nobody@globo.com","password":"123456"}

成功时返回 200。如果 JSON 非法时返回 400.如果邮件非法时返回 400.如果密码字符长度小于 6或者大于 50 时返回 400.如果邮件已存在时返回 409.

例子：

POST /users HTTP/1.1
Body: `{"email":"nobody@globo.com","password":"123456"}`

重置密码

- Method: POST- Endpoint: /users//password?token=token

成功时返回 200。找不到用户时返回 404。

token 参数是可选的。

例子：

POST /users/user@email.com/password?token=1234 HTTP/1.1

登录

- Method: POST- Endpoint: /users//tokens- Body: {"password":"123456"}

成功时返回 200。如果 JSON 非法时返回 400.如果密码为空时返回 400.找不到用户时返回 404。

例子：

POST /users/user@email.com/tokens HTTP/1.1
{"token":"e275317394fb099f62b3993fd09e5f23b258d55f"}

登出（退出）

- Method: DELETE- Endpoint: /users/tokens

成功时返回 200。

例子：

DELETE /users/tokens HTTP/1.1

当前用户的信息

- Method: GET- Endpoint: /users/info

成功时返回 200，以及一个关于当前用户信息的 JSON 数据。

例子：

GET /users/info HTTP/1.1
{"Email":"myuser@company.com","Teams":["frontend","backend","sysadmin","full stack"]}

改变密码

- Method: PUT- Endpoint: /users/password- Body: {"old":"123456","new":"654321"}

成功时返回 200。如果 JSON 非法时返回 400。如果旧或新密码为空时返回 400。如果密码字符长度小于 6 或者大于 50 时返回 400。如果旧密码与当前密码不匹配时返回 403。

例子：

PUT /users/password HTTP/1.1
Body: `{"old":"123456","new":"654321"}`

删除一个用户

- Method: DELETE- Endpoint: /users

成功时返回 200。

例子：

DELETE /users HTTP/1.1

给用户增加一个公钥

- Method: POST- Endpoint: /users/keys- Body: {"key":"my-key"}

成功时返回 200。

例子：

POST /users/keys HTTP/1.1
Body: `{"key":"my-key"}`

删除用户的公钥

- Method: DELETE- Endpoint: /users/keys- Body: {"key":"my-key"}

成功时返回 200。

例子：

DELETE /users/keys HTTP/1.1
Body: `{"key":"my-key"}`

显示 API 秘钥

- Method: GET- Endpoint: /users/api-key- Format: JSON

成功时返回 200，以及一个 body 中的 API 秘钥的 JSON 数据。

例子：

GET /users/api-key HTTP/1.1
Body: `{"token": "e275317394fb099f62b3993fd09e5f23b258d55f", "users": "user@email.com"}`

重新生成 API 秘钥

- Method: POST- Endpoint: /users/api-key

成功时返回 200。

例子：

POST /users/api-key HTTP/1.1

1.8 团队

列出团队

- Method: GET- Endpoint: /teams- Format: JSON

成功时返回 200，以及一个 body 中的团队列表的 JSON 数据。

例子：

GET /teams HTTP/1.1
Content-Length: 22
[{"name": "teamname"}]

团队的信息

- Method: GET- Endpoint: /teams/- Format: JSON

成功时返回 200，以及一个 body 中团队信息的 JSON 数据。

例子：

GET /teams/teamname HTTP/1.1
{"name": "teamname", "users": ["user@email.com"]}

增加一个团队

- Method: POST- Endpoint: /teams

成功时返回 200。

例子：

POST /teams HTTP/1.1
{"name": "teamname"}

删除一个团队

- Method: DELETE- Endpoint: /teams/

成功时返回 200。

例子：

DELELE /teams/myteam HTTP/1.1

增加用户到一个团队

- Method: PUT- Endpoint: /teams//

成功时返回 200。

例子：

PUT /teams/myteam/myuser HTTP/1.1

从团队中删除用户

- Method: DELETE- Endpoint: /teams//

成功时返回 200。

例子：

DELETE /teams/myteam/myuser HTTP/1.1

1.9 部署

部署列表

- Method: GET- Endpoint: /deploys?app=appname&service=servicename- Format: JSON

成功时返回 200，以及响应的 body 中一个包含部署列表的 JSON 数据。

此处:

• app 是 app 名字。
• service 是 service 名字。
  例子：

GET /deploys HTTP/1.1
[{"Ip":"10.10.10.10","Name":"app1","Units":[{"Name":"app1/0","State":"started"}]}]
[{"ID":"543c20a09e7aea60156191c0","App":"myapp","Timestamp":"2013-11-01T00:01:00-02:00","Duration":29955456221322857,"Commit":"","Error":""},{"ID":"543c20a09e7aea60156191c1","App":"yourapp","Timestamp":"2013-11-01T00:00:01-02:00","Duration":29955456221322857,"Commit":"","Error":""}]

获取一次部署的信息

- Method: GET- Format: JSON- Endpoint: /deploys/:deployid

成功时返回 200。部署找不到时返回 404。

例子:

GET /deploys/12345
{"ID":"54ff355c283dbed9868f01fb","App":"tsuru-dashboard","Timestamp":"2015-03-10T15:18:04.301-03:00","Duration":20413970850,"Commit":"","Error":"","Image":"192.168.50.4:3030/tsuru/app-tsuru-dashboard:v2","Log":"[deploy log]","Origin":"app-deploy","CanRollback":false,"RemoveDate":"0001-01-01T00:00:00Z"}

1.10 元数据

Tsuru API 信息

- Method: GET- Endpoint: /info- Format: JSON

成功时返回 200，以及响应的 body 中一个包含元数据的 JSON 数据。

例子：

GET /info HTTP/1.1
{"version": "1.0"}

Tsuru API 服务器的基本健康检查

- Method: GET- Endpoint: /healthcheck/- Format: text

总是返回 200 和文本 body WORKING。

例子：

GET /healthcheck/ HTTP/1.1
WORKING

所有 Tsuru 组件的完整健康检查

- Method: GET- Endpoint: /healthcheck/?check=all- Format: text

当所有组件都是 WORKING 状态时返回 200。当有任何一个组件不是 WORKING 状态时返回 500。Body 中总是包含各个组件的状态和完成检查的时间的文本。

例子：

GET /healthcheck/?check=all HTTP/1.1
MongoDB: WORKING (643.81µs)
Router Hipache: WORKING (845.457µs)
docker-registry: WORKING (1.954069ms)
Gandalf: WORKING (1.787768ms)

原文: http://doc.oschina.net/tsuru-paas?t=53193