Stackable KB :: Stackable API

Knowledgebase Home | Glossary | Favorites

Knowledgebase Home > Tutorials

Stackable API

Article Details

Last Updated
24th of August, 2010

Would you like to...

Print this page

Email this page

1. The Payload

In this tutorial we have decided that we want to create a new container. To do this we need to deliver the following payload: our customer ID, the name we would like to give the container, the desired operating system and finally the stack type. These make up the minimum components of a create request:

                $stackableCustomerId = "3005";
                $stackableContainerName = "My First Container";
              $stackableOS = "CentOS_5_x86_64";
                $stackableStack = "LAMP";

Then assemble it as the payload:
           $payload = array(
                                              "customerId"=>$stackableCustomerId,
                                              "name"=>$stackableContainerName,
                                              "os"=>$stackableOS,
                                              "stack"=>$stackableStack);

2. Building the Headers

Now we need to put together the operation specific cURL headers. Before you can do this you will first need to generate an API key. Be sure to use https in the URL, and set your port to 443 to prevent sending your key in the clear. The following are required regardless of authentication method. They are used to tell cURL where to send the payload and headers, which service and methods to call within the API and to store your API key and key ID.

        $stackableURL = "https://api.stackable.com";
        $stackableService = "Container";
        $stackableMethod = "create";
        $stackableAPIKey = "yourAPIKey";
        $stackableAPIKeyID = "yourAPIKeyID";

3. Sending With Plain Key Authentication

If we just want to use plain key authentication the next step is to put the API key and key ID together to prepare them to be sent with cURL:

        $header = array(
                       "Content-Type: application/json",
                       "Stackable-APIKey:".$stackableAPIKey,
                       "Stackable-APIKeyID:".$stackableAPIKeyID);

4. Sending with HMAC

There is an inherent risk with passing the API key over the wire with the method above. Since this key is the only thing preventing other people from doing things with your containers it should be treated as a valued secret. We therefore recommend the more secure method below. To utilize the additional security we need to do a little bit more work.

To create the HMAC key, prepend the endcode date and time to the payload, and encode as a base 64 sha1 binary hash using your API key as the hash_hmac key. For more information on hash_hmac review the PHP documentation here. Put the date into a variable so we're sure to be using the same date during the encode as in the Signature-Created cURL header later in the script:

        $encodeDate = date("c");
        $hmacSignature = base64_encode(hash_hmac('sha1', $encodeDate.$payload,$stackableAPIKey, true));

Then build the cURL header:

        $header = array(
                     "Content-Type: application/json",
                         "Signature:".$hmacSignature,
                         "Signature-Version:1",
                         "Signature-Method:HMAC/SHA1",
                         "Signature-Created:".$encodeDate,
                         "Customer-Key-ID:".$stackableAPIKeyID);

5. The cURL headers

Now we can use cURL to send the payload using the headers we've just created. Read the cURL docs for more information on these functions:

        $ch = curl_init($stackableURL."/".$stackableService."/".$stackableMethod);
       curl_setopt($ch, CURLOPT_PORT, 443);
       curl_setopt($ch, CURLOPT_POST, 1);
       curl_setopt($ch, CURLOPT_HEADER, 1);
       curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
       curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
       curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
       curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
       curl_setopt($ch, CURLOPT_VERBOSE, 1);
       $curl_result = curl_exec($ch);
       $curl_errno = curl_errno($ch);
       $curl_error = curl_error($ch);

Next, read back the results of the operation so we know it succeeded:

        print("Curl Result:[$curl_result]");

6. Working Example Code

Finally, here it is all together in a working script:

        /*Sample Code for the Stackable Service.Container.create method
          by Pete Mackay, Stackable 2009
          For Stackable API Service.Container methods and documentation please visit
          http://api.stackable.com/doc/customer/files/Service-Container-txt.html
       */


       //Payload data: Your customer ID, the name you would like to give your container,
           the OS you would like installed, and the stack (currently only LAMP is available)
       $stackableCustomerId = "3005";
       $stackableContainerName = "My First Container";
       $stackableOS = "CentOS_5_x86_64";
       $stackableStack = "LAMP";

       //API authentication. Set to 'hmac' for HMAC signature or 'key' for plain key.
       $stackableAPIAuth = "hmac";

       //cURL POST settings including the URL, Service, Method and your API key and
   key ID. Be sure to use https and set the CURLOPT_PORT to 443 below to
           prevent sending your API key in the clear.
       $stackableURL = "https://api.stackable.com";
       $stackableService = "Container";
       $stackableMethod = "create";
       $stackableAPIKey = "yourKeyGoesHere";
       $stackableAPIKeyID = "yourKeyIDGoesHere";

       //Service.Containter.create payload
       $payload = array(
                                       "customerId"=>$stackableCustomerId,
                                     "name"=>$stackableContainerName,
                                     "os"=>$stackableOS,
                                     "stack"=>$stackableStack);

       //Encode $payload for JSON
       $payload = json_encode($payload);

       if($stackableAPIAuth = "hmac"){
                                       //Get the date to use for creating the signature, and for passing the creation date to the API
                                       $encodeDate = date("c");

                                       //Create the HMAC key as a base 64 encoded sha1 binary hash of the date and JSON
                                          encoded payload appended together, and your API key as the hash_hmac key.
                                       $hmacSignature = base64_encode(hash_hmac('sha1', $encodeDate.$payload,$stackableAPIKey, true));

                                       //Build the header inluding the HMAC signature, encode date and your API key ID.
                                       $header = array(
                                                                    "Content-Type: application/json",
                                                                    "Signature:".$hmacSignature,
                                                                    "Signature-Version:1",
                                                                    "Signature-Method:HMAC/SHA1",
                                                                    "Signature-Created:".$encodeDate,
                                                                    "Customer-Key-ID:".$stackableAPIKeyID);


       } elseif($stackableAPIAuth = "key") {

                                           //cURL headers to send the API key and key ID.
                                           $header = array(
                                                                         "Content-Type: application/json",
                                                                         "Stackable-APIKey:".$stackableAPIKey,
                                                                         "Stackable-APIKeyID:".$stackableAPIKeyID);
                                             }

       //Post the HTTP request, headers and payload with cURL. Ensure you set
          CURLOPT_PORT to 443 to avoid sending your API key in the clear.
       $ch = curl_init($stackableURL."/".$stackableService."/".$stackableMethod);
       curl_setopt($ch, CURLOPT_PORT, 443);
       curl_setopt($ch, CURLOPT_POST, 1);
       curl_setopt($ch, CURLOPT_HEADER, 1);
       curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
       curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
       curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
       curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
       curl_setopt($ch, CURLOPT_VERBOSE, 1);
       $curl_result = curl_exec($ch);
       $curl_errno = curl_errno($ch);
       $curl_error = curl_error($ch);

       if ($curl_errno != 0) {
                               print("Curl Errno:[$curl_errno]
");
                               print("Curl Error:[$curl_error]
");
       }

       //return $curl_result;
       print("Curl Result:[$curl_result]
");

Congratulations, you've just created your first Stackable container using the API!

Visitor Comments

Comment #1 (Posted by Starly)
There is a criitacl shortage of informative articles like this.

No related articles were found.

Attachments