Developer's Guide

The Datapipe Stratosphere API is loosely based on the REST architecture and allows developers to create new resources and integrate existing systems with Stratosphere. It supports POST/GET requests and returns both XML and JSON response formats.  For a full list of commands, go HERE

Getting started

To get started using the Stratosphere API, you should have the following:

  • The API Key and Secret Key for an account. Your API Key and Secret key can be found on your account details screen. (https://cloud.datapipe.com/account/)
  • Familiarity with HTTP GET/POST and query strings.
  • Knowledge of either XML or JSON.
  • Knowledge of a programming language that can generate HTTP requests; for example, Java or PHP.

All Stratosphere API requests are submitted in the form of a HTTP GET/POST with an associated command and any parameters. A request is composed of the following:

  • Stratosphere API URL: This is the web services API entry point
    https://cloud.datapipe.com/api/compute/v1
  • Command: The web services command you wish to execute, such as start a virtual machine or create a disk volume
  • Parameters: Any additional required or optional parameters for the command

A sample API GET request looks like the following:

https://cloud.datapipe.com/api/compute/v1?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature
=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Signing API requests

Whenever you access the Stratosphere API it must be signed so that  Stratosphere can verify the caller has been authenticated and authorized to execute the command. Make sure that you have both the API Key and Secret Key provided for your account before proceeding with the signing process.

To show how to sign a request, we will re-use the previous example.

https://cloud.datapipe.com/api/compute/v1?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Breaking this down, we have several distinct parts to this URL.

  • Base URL: This is the base URL to the Stratosphere API
    https://cloud.datapipe.com
  • API Path: This is the path to the API Servlet that processes the incoming requests.
    /api/compute/v1?
  • Command String: This part of the query string comprises of the command, its parameters, and the API Key that identifies the account.
    command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
  • Signature: This is the hashed signature of the Base URL that is generated using a combination of the user's Secret Key and the HMAC SHA-1 hashing algorithm.
    &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Every API request has the format Base URL+API Path+Command String+Signature.

Generating the signature

  • For each field-value pair (as separated by a '&') in the Command String, URL encode each value so that it can be safely sent via HTTP GET.

    NOTE: Make sure all spaces are encoded as '%20' rather than '+'.

  • Lower case the entire Command String and sort it alphabetically via the field for each field-value pair.  The result of this step would look like the following.
    apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
  • Take the sorted Command String and run it through the HMAC SHA-1 hashing algorithm (most programming languages offer a utility method to do this) with the user's Secret Key.  Base64 encode the resulting byte array in UTF-8 so that it can be safely transmitted via HTTP.  The final string produced after Base64 encoding should be 'Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D'.

By reconstructing the final URL in the format Base URL+API Path+Command String+SignaEFASSture, the final URL should look like:

https://cloud.datapipe.com/api/compute/v1?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature
=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D

Response formats

Stratosphere supports two formats as the response to an API call. The default response is XML. If you would like the response to be in JSON, add &response=json to the Command String.

Sample XML Response:

<listserviceofferingsresponse>
  <serviceoffering>
    <name>nano-h-5</name>
    <offerha>true</offerha>
    <cpuspeed>1200</cpuspeed>
    <storagetype>shared</storagetype>
    <memory>512</memory>
    <displaytext>0.5 CPU core, 512MB memory</displaytext>
    <networkrate>1000</networkrate>
    <issystem>false</issystem>
    <id>52</id>
    <limitcpuuse>true</limitcpuuse>
    <cpunumber>1</cpunumber>
    <defaultuse>false</defaultuse>
    <created>2011-11-09T01:06:03-0500</created>
  </allocatedipaddress>
  <count>1</count>
</listipaddressesresponse>

Sample JSON Response:

{"listserviceofferingsresponse"=>
  {"serviceoffering"=>[
    {"name"=>"nano-h-5",
      "offerha"=>true,
      "cpuspeed"=>1200,
      "storagetype"=>"shared",
      "memory"=>512,
      "displaytext"=>"0.5 CPU core, 512MB memory",
      "networkrate"=>1000,
      "issystem"=>false,
      "id"=>52,
      "limitcpuuse"=>true,
      "cpunumber"=>1,
      "defaultuse"=>false,
      "created"=>"2011-11-09T01:06:03-0500"}
    ],
    "count"=>1
  }
}

Maximum results returned

The default page size returned is 500 results.

To decrease the page size limit for an individual API command, override the default setting with the page and pagesize parameters, which are available in any list* command (listCapabilities, listDiskOfferings, etc.).

  • Both parameters must be specified together. The value of the pagesize parameter must be smaller than the value of default.page.size. That is, you can not increase the number of possible items in a result page, only decrease it.
  • For syntax information on the list* commands, see the API Reference.

Error handling

If an error occurs while processing an API request, the appropriate response in the format specified is returned. Each error response consists of an error code and an error text describing what possibly can go wrong.

An HTTP error code of 401 is always returned if API request was rejected due to bad signatures, missing API Keys, or the user simply did not have the permissions to execute the command.

Asynchronous commands

Commands are designated as asynchronous when they can potentially take a long period of time to complete such as creating a snapshot or disk volume.

They differ from synchronous commands by the following:

  • They are identified in the API Reference by an (A).
  • They will immediately return a job ID to refer to the job that will be responsible in processing the command.
  • If executed as a "create" resource command, it will return the resource ID as well as the job ID.
  • You can periodically check the status of the job by making a simple API call to the command, queryAsyncJobResult and passing in the job ID.

Job status

The key to using an asynchronous command is the job ID that is returned immediately once the command has been executed. With the job ID, you can periodically check the job status by making calls to queryAsyncJobResult command.

The command will return three possible job status integer values:

  • 0 - Job is still in progress. Continue to periodically poll for any status changes.
  • 1 - Job has successfully completed. The job will return any successful response values associated with command that was originally executed.
  • 2 - Job has failed to complete. Please check the tag for failure reason code and for the failure reason.
Related Pages: Commands