REST API Method Reference


This article describes each Temboo REST API endpoint in detail. For each, you'll find (where applicable) samples of the JSON format used for the request and response, along with a sample cURL script to help you test and debug them. Here's the list of endpoints discussed:

List Available Choreos

GET /choreos

Retrieve a list of the Choreos that are accessible to the user whose credentials were supplied in the request.

Response format:

{
  "resources": [
    "\/SharedChoreos\/Choreos\/TestChoreo1",
    "\/SharedChoreos\/Choreos\/TestChoreo1"
  ]
}

Sample cURL script:

curl -k --basic -u APP_NAME:APP_KEY --header "Accept: application/json" --header "Content-Type: application/json"  --header "x-temboo-domain: /ACCOUNT_NAME/master" https://ACCOUNT_NAME.temboolive.com:443/temboo-api/1.0/choreos

List Specified Choreo Details

GET /choreos/<id>

Retrieve details for the specified Choreo, including its:

Sample response format:

{
  "valid": "true",
  "outputs": {
    "myOutput": {
      "description": "textual description for output.",
      "type": "STRING_VARIABLE"
    }
  },
  "inputs": {
    "myInput1": {
      "description": "textual description for input 1.",
      "type": "STRING_VARIABLE"
    },
    "myInput2": {
      "description": "textual description for input 1.",
      "type": "STRING_VARIABLE"
    }
  }
}

Sample cURL script:

curl -k --basic -u APP_NAME:APP_KEY --header "Accept: application/json" --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" https://ACCOUNT_NAME.temboolive.com:443/temboo-api/1.0/choreos/myFolder/myChoreo

Run a Choreo

POST /choreos/<id>

Run the specified Choreo. If the POST body is empty, no inputs will be provided to the Choreo. Optionally, input values for each input variable defined in the Choreo can be submitted in the POST body. The set of available inputs can be retrieved via the GET /choreos/<id> method.

Returns a JSON or XML response containing the execution ID of the Choreo instance that's been launched.

Sample cURL script to run a Choreo without inputs:

curl --basic -u APP_NAME:APPKEY --header "Accept: application/json" --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" -X POST "https://ACCOUNT_NAME.temboolive.com:443/temboo-api/1.0/choreos/myFolder/myChoreo"

When running a Choreo with input values, those inputs must be provided in the body of the POST request as a set of key/value pair elements corresponding to the inputs defined in the Choreo metadata. For example, to run a Choreo with two inputs named "input1" and "input2" and specify values for those inputs as "foo" and "bar", respectively, the following JSON would be used:

{
  "inputs": [
    {
      "name": "input1",
      "value": "foo"
    },
    {
      "name": "input2",
      "value": "bar"
    }
  ]
}

If you're setting the Accept and Content-Type headers to "application/xml", you can provide XML for the input set instead:

<inputs>
  <input>
      <name>input1</name>
      <value>foo</value>
  </input>
  <input>
      <name>input2</name>
      <value>bar</value>
  </input>
</inputs>

Note: If you specify an input that's not present in the Choreo, it's ignored; each input can only be specified once in the XML or JSON request body.

Sample cURL script to run a Choreo with a JSON input set:

curl --basic -u APP_NAME:APPKEY --header "Accept: application/json" --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" -X POST --data "{"inputs":[{"name":"input1","value":"foo"},{"name":"input2","value":"bar"}]}" "https://ACCOUNT_NAME.temboolive.com:443/temboo-api/1.0/choreos/myFolder/myChoreo"

Sample cURL script to run a Choreo with an XML input set:

curl --basic -u APP_NAME:APPKEY --header "Accept: application/xml" --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/xml" -X POST --data "<inputs><input><name>input1</name><value>foo</value><input><input><name>input2</name><value>bar</value></input></inputs>" "https://ACCOUNT_NAME.temboolive.com:443/temboo-api/1.0/choreos/SharedChoreos/testChoreo"

Sample JSON response from a successful Choreo run (with or without inputs):

{
  "output": {
    "Response": "The response body will be here"
  },
  "execution": {
    "endtime": "1394643340635",
    "id": "8a5cfd72449539570144b7388b1073d5",
    "starttime": "1394643340083",
    "status": "SUCCESS"
  }
}

Sample XML response from a successful "run choreo" operation (with or without inputs):

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<execution>
    <id>8af833203b3ee65e013b42c4093d45b2</id>
    <status>SUCCESS</status>
    <starttime>1354034841918</starttime>
    <endtime>1354034841933</endtime>
    <outputs>
        <output>
            <name>Response</name>
            <value>The response body will be here</value>
        </output>
    </outputs>
</execution>

List Running Choreos

GET /choreo-executions

List the IDs of all currently running Choreos to which the user whose credentials are specified in the request has access.

Sample response format:

{
  "executions": [
    {
      "id": "8ad7c596449531dd0144b7e8400479a6",
      "choreo": "\/myFolder\/myChoreo",
      "starttime": "1394654855245",
      "host": "10.60.130.49",
      "status": "RUNNING"
    }
  ]
}

Sample cURL script:

curl -v --basic -u APP_NAME:APP_KEY --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" --header "Accept: application/json" "https://ACCOUNT_NAME.temboolive.com/temboo-api/1.0/choreo-executions"

Note: Only currently running Choreos are returned in the list of executions from this operation.

Retrieve Status of Specific Execution

GET /choreo-executions/<id>

Retrieve the status of a specific Choreo execution, by execution ID. The returned data indicates the current state of the Choreo, which is one of the following:

The status of a specific Choreo execution is guaranteed to be available for at least five minutes after that execution completes.

Sample response data format:

{
  "execution": {
    "endtime": "1394654915494",
    "id": "8ad7c596449531dd0144b7e8400479a6",
    "choreo": "\/Choreos\/myChoreo",
    "starttime": "1394654855245",
    "host": "10.60.130.49",
    "status": "SUCCESS"
  }
}

Sample cURL script:

curl -v --basic -u APP_NAME:APP_KEY --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" --header "Accept: application/json" "https://ACCOUNT_NAME.temboolive.com/temboo-api/1.0/choreo-executions/8ad7c596449531dd0144b7e8400479a6"

Terminate a Specific Running Choreo Execution

DELETE /choreo-executions/<id>

Terminate a specific running Choreo execution, by ID.

Sample cURL script:

curl -v --basic -u APP_NAME:APP_KEY --header "x-temboo-domain: /ACCOUNT_NAME/master" --header "Content-Type: application/json" --header "Accept: application/json" -X DELETE "https://ACCOUNT_NAME.temboolive.com/temboo-api/1.0/choreo-executions/8ad7c596449531dd0144b7e8400479a6"

A 204 response code, with no body content, is returned upon a successful terminate-Choreo request.

Note: When a termination request is received, running Choreos terminate upon completion of their current step to prevent data loss.

What next?

Now you're ready to run any of our 2000+ Choreos using the REST API. You're just a few steps away from making something extraordinary.

Need help?

We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.


Back