2014-05-20-how-to-use-runabove-api.markdown

layout	title	categories	author	lang
post	How to use RunAbove API?	Instances	VincentCasse	en

RunAbove has been designed to help developers in building scalable software faster. To create applications with our product, we provide an API for each of our products. But, how do you use our api ?

API capabilities

To discover all possibilities of our APIs, you could use the automated console available here : https://api.runabove.com/console/. In the console, you can see the documentation of APIs and you can test each of the calls available .

Note : The RunAbove API is designed to be very simple. If you want to deal directly with Openstack API, you can authenticate with Keystone in https://auth.runabove.io/.

More information about how to use Openstack APIs for Object Storage, Instances and Authentication

How to authenticate a user?

First, you have to declare your application in the API to be authorized to communicate with RunAbove API. To declare a new application, you can fill in the form found at the following page : https://api.runabove.com/createApp/. This application will be linked to your account with a specific name and description. You need to save your application key and application secret to identify your requests.

If you want to develop an application with RunAbove API, you have to use a token, called a consumer key for each API's request. To get this token, you must go to this url https://api.runabove.com/1.0/auth/credential with some data inside the body of the request:

curl    -X POST \
        -H 'X-Ra-Application: z5czlUfqJL6HsYKj' \
        -H 'Content-Type: application/json' \
        -d '{
            "accessRules":
                [
                    { "method":"GET","path":"/me"}
                ],
                "redirection":"http://runabove.com"
            }' \
        "https://api.runabove.com/1.0/auth/credential"

This request contains your application key included in metadata and requires that the access rules be listed inside the body.

Access rules define which call will be authorized when the consumer key is used. For example, here, the application can only call /me but you can add requests as required. You can precisely define which calls each app has access to: you can use regex to declare with request will be authorize in the consumer key. If you want get vnc console of all your instances, you could authorize your application with this accessRules :

{ "method":"GET","path":"/instance/*/vnc"}

In return to this request, you will get the consumer key and a url. In this url, a user can validate the consumer key with their authentication.

How to call the API?

Now that you have the application's credentials and consumer key validated, by user login, you can call our API. For example to get a list of your instances. To do this, you need to send a request to https://api.runabove.com/1.0/instance with the following.

$ curl  -XGET
        -H 'X-Ra-Application:your_application_key' \
        -H 'X-Ra-Timestamp:current_timestamp'   \
        -H 'X-Ra-Signature:generated_signature' \
        -H 'X-Ra-Consumer:the_consumer_key'  \
        https://api.runabove.com/1.0/instance

To reduce differences between your local timestamp and timestamp inside API's servers, you can get the current timestamp of our servers with a call on https://api.runabove.com/1.0/auth/time.

$ curl https://api.runabove.com/1.0/auth/time
  1400000000

With this information, you can calculate the difference between timestamps and add it on your local timestamp on each request.

Signature is a sha1, in hexadecimal format, composed by a string with some information separated by + character: your application secret, the consumer key, HTTP verb, query, body of the request and timestamp.

$ echo -n "your_application_secret_key+application_consumer_key+GET+https://api.runabove.com/1.0/instance++1400000000" | openssl dgst -sha1 | awk '{print $2}'
d33fced42c337a8dfc15d6b7a8e0c588d3a0f62f

Prepend $1$ to the signature so it becomes:

$1$d33fced42c337a8dfc15d6b7a8e0c588d3a0f62f

Congratulations!

You have your first request on RunAbove API! Now you can create applications on object storage or automate your infrastructure with some creation of new instances!