• API工作流
  • 验证
  • Content-types
  • 列出可用计划
  • 创建一个新的实例
  • 将服务实例绑定到应用
  • 从服务实例解绑定应用
  • 删除实例
  • 检查实例的状态
  • 实例的额外信息

    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