API工作流

tsuru发送给service API请求类型有下面几种：

  • 创建一个服务的实例 (tsuru service-add)
  • 为应用绑定一个服务实例 (tsuru service-bind)
  • 将服务从应用解除绑定 (tsuru service-unbind)
  • 销毁服务实例 (tsuru service-remove)
  • 检查服务实例的状态 (tsuru service-status)
  • 显示服务的额外信息，包括实例以及可用的计划(tsuru service-info)

验证

tsuru通过service API使用HTTP基本验证去做做身份验证。用户可以是用户名或者是服务名，密码定义在构建你的服务中服务清单部分。

Content-types

tsuru 在请求中使用application/x-www-form-urlencoded，期望返回application/json。

下面是一个tsuru请求service API请求的例子：

  1.     POST /resources HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Content-Length: 38
  5.     Accept: application/json
  6.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  7.     Content-Type: application/x-www-form-urlencoded
  9.     name=myinstance&plan=small&team=myteam

列出可用计划

当用户运行service-info命令时，tsuru会列出所有可用的计划：

  1.     $ tsuru service-info mysql

通过tsuru的service API /resources/plans GET请求，它会显示用可以访问的服务所有的实例，包括计划的列表。请求的例子如下：

  1.     GET /resources/plans HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Accept: application/json
  5.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  6.     Content-Type: application/x-www-form-urlencoded

API应当返回下面的HTTP返回码及其消息体：

  1. * 200: 操作成功。消息体为JSON格式，包括计划列表。每个计划包含"name"和"description"。消息体例子如下：
  2.     HTTP/1.1 200 OK
  3.     Content-Type: application/json; charset=UTF-8
  5.     [{"name":"small","description":"plan for small instances"},
  6.      {"name":"medium","description":"plan for medium instances"},
  7.      {"name":"huge","description":"plan for huge instances"}]

在失败的情况下，service API返回500，消息体内会解释具体的错误。

创建一个新的实例

当tsuru用户通过命令行工具创建了一个服务实例时，这个过程就开始了：

  1.     $ tsuru service-add mysql mysql_instance

tsuru将名字、计划和拥有实例的团队作为参数，通过往service API的/resources发送POST请求（请注意tsuru不包含尾斜杠）。

  1.     POST /resources HTTP/1.1
  2.     Host: myserviceapi.com
  3.     Content-Length: 56
  4.     User-Agent: Go 1.1 package http
  5.     Accept: application/json
  6.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  7.     Content-Type: application/x-www-form-urlencoded
  9.     name=mysql_instance&plan=small&team=myteam&user=username

API应该会返回下面的HTTP返回码和消息体：

  1. * 201: 实例成功创建后返回。tsuru没有期望在返回的消息体中看到成功的信息，所以没有必要包含任何消息体。
  2. * 500: 操作错误时返回。tsuru期望在service API返回的消息体中看到关于错误的解释。

将服务实例绑定到应用

当tsuru客户通过命令行将应用绑定到一个服务实例时，这个过程就开始了：

  1.     $ tsuru service-bind mysql mysql_instance --app my_app

现在，tsuru服务有两个绑定端点：/resources/<service-instance-name>/bind和 /resources/<service-instance-name>/bind-app.

每次应用添加单元的时候都会调用第一个端点。这个端点是一个POST请求，加上app-host和uniti-host参数，app-host代表app能访问的主机，unit-host是单元的地址。下面是请求的例子：

  1.     POST /resources/myinstance/bind HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Content-Length: 48
  5.     Accept: application/json
  6.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  7.     Content-Type: application/x-www-form-urlencoded
  9.     app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

当应用绑定到服务时，会调用第二个端点/resources/<service-instance-name>/bind-app。这个端点是一个POST请求，外加app-host参数，app-host代表应用能访问的主机。下面是请求的例子：

  2.     POST /resources/myinstance/bind-app HTTP/1.1
  3.     Host: myserviceapi.com
  4.     User-Agent: Go 1.1 package http
  5.     Content-Length: 48
  6.     Accept: application/json
  7.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  8.     Content-Type: application/x-www-form-urlencoded
  10.     app-host=myapp.cloud.tsuru.io

service API应当会返回下面的HTTP返回码以及消息体：

  1. * 201: 如果应用成功绑定到服务。返回的JSON消息体必须包含这个实例的环境变量，这样应用可以设置它们来连接到实例上。如果服务没有任何环境变量可以设置，它返回的消息体是`null`或者`{}`。返回的例子如下：
  1.     HTTP/1.1 201 CREATED
  2.     Content-Type: application/json; charset=UTF-8
  4.     {"MYSQL_HOST":"10.10.10.10","MYSQL_PORT":3306,
  5.      "MYSQL_USER":"ROOT","MYSQL_PASSWORD":"s3cr3t",
  6.      "MYSQL_DATABASE_NAME":"myapp"}

过程中的错误状态码如下：

  1. * 404: 如果服务实例不存在。消息体内不需要包含任何内容。
  2. * 412: 如果服务实例仍然在配置的过程中，还不能进行绑定。service API可能会在消息体中包含一些失败原因的解释。
  3. * 500: 操作中出现任何错误。tsuru期望service API可以在消息体中包含错误的解释。

从服务实例解绑定应用

当tsuru用户通过命令行将一个服务实例从应用解绑定时，过程开始：

  1.     $ tsuru service-unbind mysql mysql_instance --app my_app

现在，tsuru有两个解绑定端点：/resources/<service-instance-name>/bind和/resources/<service-instance-name>/bind-app。第一个端点会在应用每次删除一个单元的时候调用。这个端点时一个DELETE请求，包含app-host和unit-host参数。请求的例子如下：

  1.     DELETE /resources/myinstance/bind HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Accept: application/json
  5.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  6.     Content-Type: application/x-www-form-urlencoded
  8.     app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

第二个端点/resources/<service-instance-name>/bind-app将在应用和服务绑定被解除后运行。该端点是一个DELETE请求，包含app-host参数。请求的例子如下：

  1.     DELETE /resources/myinstance/bind-app HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Accept: application/json
  5.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  6.     Content-Type: application/x-www-form-urlencoded
  8.     app-host=myapp.cloud.tsuru.io

API应该返回下面的HTTP返回码和对应的消息体：

  1. * 200: 如果操作成功并且应用不再绑定到服务实例。消息体内不需要包含任何内容。
  2. * 404: 如果服务实例不存在。消息体内不需要包含任何内容。
  3. * 500: 操作中出现任何错误。tsuru期望service API可以在消息体中包含错误的解释。

删除实例

当tsuru用户通过命令行删除服务实例时，这个过程就开始了。：

  1.     $ tsuru service-remove mysql mysql_instance -y

tsuru通过DELETE请求去调用service API的/resources/<service-name>去删除实例（请注意tsuru不包含尾斜线）。请求的例子如下：tsuru calls the service API to remove the instancevia DELETE on

  1.     DELETE /resources/myinstance HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Accept: application/json
  5.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  6.     Content-Type: application/x-www-form-urlencoded

API应该返回下面的HTTP返回码和对应的消息体：

  1. * 200: 如果服务实例删除成功。消息体内不需要包含任何内容。
  2. * 404: 如果服务实例不存在。消息体内不需要包含任何内容。
  3. * 500: 操作中出现任何错误。tsuru期望service API可以在消息体中包含错误的解释。

检查实例的状态

当tsuru用户通过命令行检查实例的状态，这个过程就开始了：

  1.     $ tsuru service-status mysql mysql_instance

tsuru通过GET请求调用 service API的/resources/mysql_instance/status去检查实例状态（请注意tsuru不包含尾斜线）。请求的例子如下：

  1.     GET /resources/myinstance/status HTTP/1.1
  2.     Host: myserviceapi.com
  3.     User-Agent: Go 1.1 package http
  4.     Accept: application/json
  5.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  6.     Content-Type: application/x-www-form-urlencoded

API应该返回下面的HTTP返回码和对应的消息体：

  1. * 202: 实例仍在配置中（待定）。消息体内不需要包含任何内容。
  2. * 204: 实例在运行，并且可以连接（运行中）。
  3. * 500: 实例没有在运行，或者还不能连接。tsuru期望消息体中有具体原因的解释。

实例的额外信息

当用户运行tsuru service-info <service>时，tsuru会获得所有实例的信息。service API有一个可选的端点。有些服务没有提供实例的额外信息。请求的例子如下：

  2.     GET /resources/myinstance HTTP/1.1
  3.     Host: myserviceapi.com
  4.     User-Agent: Go 1.1 package http
  5.     Accept: application/json
  6.     Authorization: Basic dXNlcjpwYXNzd29yZA==
  7.     Content-Type: application/x-www-form-urlencoded

API应该返回下面的HTTP返回码和对应的消息体：

  1. * 404: API没有关于服务实例的额外信息。消息体内不需要包含任何内容。
  2. * 200: 服务实例有额外的信息。返回消息体必须是一个包含项目列表的JSON。每个项目都是一个JSON对象，由标签和值组成。返回的例子如下：
  1.     HTTP/1.1 200 OK
  2.     Content-Type: application/json; charset=UTF-8
  4.     [{"label":"my label","value":"my value"},
  5.      {"label":"myLabel2.0","value":"my value 2.0"}]

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