Working with the Temboo REST API

The Temboo REST API allows you to make HTTP requests to perform a variety of CRUD operations. The REST API includes methods to:

Retrieve a list of Choreos that you're able to run
Retrieve detailed information, such as inputs, status, and description data for a specific Choreo
Run a Choreo, optionally providing input values to use in that execution
Retrieve the list of currently running Choreo executions
Retrieve the status of a Choreo that has been executed via the API
Terminate a currently running Choreo execution

At a high level, HTTP GET requests are used to retrieve information from the API, such as Choreo IDs, whereas HTTP POST requests are used to execute Choreos. All API actions return XML or JSON data. cURL code snippets are available from the Library to show how you can use the REST API directly.

No matter what operation you're performing, each request you make to the Temboo REST API must include the following:

A special "Temboo Domain" HTTP request header, which specifies the name of your Temboo account
Authentication information for your request, in the form of a username/password combination
"Accept" and "Content-Type" headers, specifying the data format you want to use for that request (XML or JSON)

Temboo Domain Request Header

The required Temboo Domain request header should be in the format:

x-temboo-domain: /ACCOUNT_NAME/master

For example, if your Temboo account name is "FooCorp", you should send the following domain header:

x-temboo-domain: /FooCorp/master

Authentication

The Temboo REST API uses HTTP Basic authentication to verify your credentials. When your application makes a request to the API, you must include an "Authorization" header containing a valid Temboo username and password.

Note: your application name and application key can be used in place of your username and password.

The HTTP Basic authentication format requires that you construct a string consisting of <username>:<password> (or <app_name>:<app_key>) and then Base64 encode the string before transmitting it as the value of the "Authorization" header. For example, if your username is "Aladdin" and your password is "open sesame", your HTTP Basic authentication string would be:

Aladdin:open sesame

The value of this string would then be Base64 encoded to "QWxhZGRpbjpvcGVuIHNlc2FtZQ==" and transmitted in an HTTP header in the format:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Accept and Content-Type Headers

Each request to the Temboo API must contain an "Accept" header indicating the type of response your client expects, and a "Content-Type" header indicating the format in which the request is being sent. For both headers, the possible values are:

application/xml (for XML data)
application/json (for JSON data)

Temboo API URL Structure

The name of your Temboo account is passed in the URLs of HTTP requests made to the API. Here's the general format of API URLs:

https://<account name>.temboolive.com/temboo-api/1.0/

For example, if your subscription name is "FooCorp" and you want to retrieve a list of available Choreos, your request URL is:

https://foocorp.temboolive.com/temboo-api/1.0/choreos

Note: All requests to the Temboo API must be made via the HTTPS protocol to keep your information secure.

The following table shows the basic set of supported API actions. Detailed information on each action can be found here.

Action	Method	URL	Notes
List available Choreos	GET	/choreos/<id>	No additional parameters needed
List specific Choreo details	GET	/choreos/<id>	Where <id> is the identifier for a specific Choreo, returned by the /choreos action
Execute a Choreo	POST	/choreos/<id>	Where <id> is the identifier of the Choreo to run; input values can optionally be provided in the POST body
List currently running Choreos	GET	/choreo-executions	No additional parameters needed
List details for a specific Choreo execution	GET	/choreo-executions/<id>	Where <id> is the identifier for a specific execution, returned by the /choreo-executions action
Terminate a running Choreo	DELETE	/choreo-executions/<id>	Where <id> is the identifier for a specific execution, returned by the /choreo-executions action

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