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:
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
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
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>
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.
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"
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.
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.
We're always happy to help. Just email us at support@temboo.com, and we'll answer your questions.