API workflow

tsuru sends requests to the service API to the following actions:

  • create a new instance of the service (tsuru service-instance-add)
  • update a service instance (tsuru service-instance-update)
  • bind an app with the service instance (tsuru service-instance-bind)
  • unbind an app from the service instance (tsuru service-instance-unbind)
  • destroy the service instance (tsuru service-instance-remove)
  • check the status of the service instance (tsuru service-instance-status)
  • display additional info about a service, including instances and availableplans (tsuru service-info and tsuru service-instance-info)

API Specification

The API specification is available as an OpenAPI v3 specification atSwaggerHuband as a yaml file here.

Authentication

tsuru will authenticate with the service API using HTTP basic authentication.The user can be username or name of the service, and the password is defined in theservice manifest.

Content-types

tsuru uses application/x-www-form-urlencoded in requests and expectapplication/json in responses.

Here is an example of a request from tsuru, to the 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
  8.  
  9. name=myinstance&plan=small&team=myteam

Listing available plans

tsuru will list the available plans whenever the user issues the commandservice-info

  1. $ tsuru service-info mysql

It will display all instances of the service that the user has access to, andalso the list of plans, that tsuru gets from the service API by issuing a GETon /resources/plans. Example of request:

  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

The API should return the following HTTP response codes with the respectiveresponse body:

- 200: if the operation has succeeded. The response body should include thelist of the plans, in JSON format. Each plan contains a “name” and a“description”. Example of response:
  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3.  
  4. [{"name":"small","description":"plan for small instances"},
  5.  {"name":"medium","description":"plan for medium instances"},
  6.  {"name":"huge","description":"plan for huge instances"}]

In case of failure, the service API should return the status 500, explainingwhat happened in the response body.

Creating a new instance

This process begins when a tsuru user creates an instance of the servicevia command line tool:

  1. $ tsuru service-instance-add mysql mysql_instance

tsuru calls the service API to create a new instance via POST on /resources(please notice that tsuru does not include a trailing slash) with the name,plan, tags and the team that owns the instance. Example of request:

  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
  8.  
  9. name=mysql_instance&plan=small&team=myteam&user=username&tag=tag1&tag=tag2

The API should return the following HTTP response codes with the respectiveresponse body:

- 201: when the instance is successfully created. There’s no need toinclude any body, as tsuru doesn’t expect to get any content back in caseof success.- 500: in case of any failure in the operation. tsuru expects that theservice API includes an explanation of the failure in the response body.

Updating a service instance

This endpoint implementation is optional. The process begins when a tsuruuser updates properties of a service instance via command line tool:

  1. $ tsuru service-instance-update mysql mysql_instance --description "new-description" --tag "tag1" --tag "tag2" --team-owner "new-team-owner" --plan "new-plan"

tsuru calls the service API to inform the instance update via PUT on /resources(please notice that tsuru does not include a trailing slash) with the new, updatedfields (description, tags, team owner and plan). Example of request:

  1. PUT /resources/mysql_instance HTTP/1.1
  2. Host: myserviceapi.com
  3. Content-Length: 79
  4. User-Agent: Go 1.1 package http
  5. Accept: application/json
  6. Authorization: Basic dXNlcjpwYXNzd29yZA==
  7. Content-Type: application/x-www-form-urlencoded
  8.  
  9. description=new-description&tag=tag1&tag=tag2&team=new-team-owner&plan=new-plan

The API should return the following HTTP response codes with the respectiveresponse body:

- 200: when the instance is successfully updated. There’s no need toinclude any body, as tsuru doesn’t expect to get any content back in caseof success.- 404: as this endpoint is optional, a 404 response code from the API isignored by tsuru.- 500: in case of any failure in the operation. tsuru expects that theservice API includes an explanation of the failure in the response body.

Binding an app to a service instance

This process begins when a tsuru user binds an app to an instance of theservice via command line tool:

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

Now, tsuru services has two bind endpoints:/resources/<service-instance-name>/bind and/resources/<service-instance-name>/bind-app.The first endpoint will be called every time an app adds an unit.This endpoint is a POST with:

- app-host the host to which the app is accessible- app-name the name of the app- unit-host the address of the unit
Example of request:
  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
  8.  
  9. app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

The second endpoint /resources/<service-instance-name>/bind-app will becalled once when an app is bound to a service. This endpoint is a POST with:

- app-host the host to which the app is accessible- app-name the name of the app

Example of request:

  1. POST /resources/myinstance/bind-app 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
  8.  
  9. app-host=myapp.cloud.tsuru.io&app-name=myapp

The service API should return the following HTTP response code with therespective response body:

- 201: if the app has been successfully bound to the instance. The responsebody must be a JSON containing the environment variables from thisinstance that should be exported in the app in order to connect to theinstance. If the service does not export any environment variable, it canreturn null or {} in the response body. Example of response:
  1. HTTP/1.1 201 CREATED
  2. Content-Type: application/json; charset=UTF-8
  3.  
  4. {"MYSQL_HOST":"10.10.10.10","MYSQL_PORT":3306,
  5.  "MYSQL_USER":"ROOT","MYSQL_PASSWORD":"s3cr3t",
  6.  "MYSQL_DATABASE_NAME":"myapp"}

Status codes for errors in the process:

- 404: if the service instance does not exist. There’s no need to includeanything in the response body.- 412: if the service instance is still being provisioned, and not readyfor binding yet. The service API may include an explanation of thefailure in the response body.- 500: in case of any failure in the operation. tsuru expects that theservice API includes an explanation of the failure in the response body.

Unbind an app from a service instance

This process begins when a tsuru user unbinds an app from an instance ofthe service via command line:

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

Now, tsuru services has two unbind endpoints:/resources/<service-instance-name>/bind and/resources/<service-instance-name>/bind-app.The first endpoint will be called every time an app removes an unit.This endpoint is a DELETE with app-host and unit-host. Example of request:

  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
  7.  
  8. app-host=myapp.cloud.tsuru.io&unit-host=10.4.3.2

The second endpoint /resources/<service-instance-name>/bind-app will becalled once when the binding between a service and an application is removed.This endpoint is a DELETE with app-host. Example of request:

  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
  7.  
  8. app-host=myapp.cloud.tsuru.io&app-name=myapp

The API should return the following HTTP response code with the respectiveresponse body:

- 200: if the operation has succeed and the app is not bound to the serviceinstance anymore. There’s no need to include anything in the responsebody.- 404: if the service instance does not exist. There’s no need to includeanything in the response body.- 500: in case of any failure in the operation. tsuru expects that theservice API includes an explanation of the failure in the response body.

Removing an instance

This process begins when a tsuru user removes an instance of the servicevia command line:

  1. $ tsuru service-instance-remove mysql mysql_instance -y

tsuru calls the service API to remove the instancevia DELETE on/resources/<service-name> (please notice that tsuru does not include atrailing slash). Example of request:

  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

The API should return the following HTTP response codes with the respectiveresponse body:

- 200: if the service instance has been successfully removed. There’s noneed to include anything in the response body.- 404: if the service instance does not exist. There’s no need to includeanything in the response body.- 500: in case of any failure in the operation. tsuru expects that theservice API includes an explanation of the failure in the response body.

Checking the status of an instance

This process begins when a tsuru user wants to check the status of aninstance via command line:

  1. $ tsuru service-instance-status mysql mysql_instance

tsuru calls the service API to check the status of the instance via GET on/resources/mysql_instance/status (please notice that tsuru does not includea trailing slash). Example of request:

  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

The API should return the following HTTP response code, with the respectiveresponse body:

- 202: the instance is still being provisioned (pending). There’s no needto include anything in the response body.- 204: the instance is running and ready for connections (running).- 500: the instance is not running, nor ready for connections. tsuruexpects an explanation of what happened in the response body.

Additional info about an instance

When the user run tsuru service-info <service> ortsuru service-instance-info, tsuru will get informationsfrom all instances. This is an optional endpoint in the service API. Someservices does not provide any extra information for instances. Example ofrequest:

  1. GET /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

The API should return the following HTTP response codes:

- 404: when the API doesn’t have extra info about the service instance.There’s no need to include anything in the response body.- 200: when there’s extra information of the service instance. The responsebody must be a JSON containing a list of items. Each item is a JSONobject combosed by a label and a value. Example response:
  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3.  
  4. [{"label":"my label","value":"my value"},
  5.  {"label":"myLabel2.0","value":"my value 2.0"}]

原文: https://docs.tsuru.io/1.6/services/api.html