API Documentation

From Atlantic.Net Knowledge Base

Jump to: navigation, search

Atlatic.Net Cloud Servers API offers a RESTful query-based Interface to programmatically access your Atlantic.Net Cloud services.

The current version is 2010-12-30 Release(0.9)

The API can only be accessed over the secure HTTPS protocol.

To make API calls you will need your API Key and you API private key, which can be found in your Cloud Administration Panel under the menu "API Info". Please note that you should never share your API private key with anyone. Also, never send us the API private key in any API calls you make. We will never ask you for your private key in any communication.


Contents

API Methods

Inputs

Certain arguments are required no matter which API method you are calling. The following table lists the required inputs. There could be other required parameters depending on the method you are calling. Please see the documentation page for required inputs for that specific method.

Input values must be URL-encoded. This is especially necessary for the Signature input.


Required Name Version Type Description
Required Version 2010-12-30 String Version of the API. E.g. 2010-12-30
ACSAccessKeyId 2010-12-30 String Your API Key
Format 2010-12-30 String The expected format you need the response to be in. Possible values: json, xml
Timestamp 2010-12-30 int The date and time at which the request has been signed. Normally, this would be the current time on your server posted in the unix seconds since epoch format. This input is also used to create the Signature as described in the section 'Making Secure Requests' on this page. E.g. 1293131636
Rndguid 2010-12-30 String A randomly generated sequence of characters. This input is also used to create the Signature. E.g. 25734727CE4C4473851881828973866F8C89
Signature 2010-12-30 String This input is a base 64 encoded, hash of the Timestamp and Rndguid using the SHA256 implementation as described above. E.g. pHjZAShlX8MdOlrJuQxquWWvUmFdIBvTAvck4K%2B5EVQ%3D
Action 2010-12-30 String This input lets you describe the API method you wish to invoke E.g. describe-instance

Making Secure Requests

All requests are accepted only over HTTPS.

All requests are required to include a Signature input computed using a base 64 encoded, SHA256 encrypted HASH generated from the request timestamp and a random GUID. The encryption needs to be done using the client API Private key.

We receive the signature with your request, and we run the similar operation at our end on the timestamp and the random GUID you sent us. This lets us verify that that you are the account holder sending the request.

Here is the suggested method to compute the Signature:

  • 1) Capture the timestamp on your local machine. Using PHP, you can do

$currtime = time();

  • 2) Generate a random GUID using a randomizer function. Using PHP, you can do

$rndguid = generate_guid(); function generate_guid(){return sprintf('%04X%04X%04X%04X%04X%04X%04X%04X%04X',mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(32768, 49151)); }

  • 3) Concatenate the random GUID to the end of the timestamp. Using PHP you can do

$string_to_sign = $currtime .$rndguid;

  • 4) Generate a hash signature using the implementation of SHA-256 encryption method. Using PHP you can do

$signature = hash_hmac('sha256', $string_to_sign, $apiprivkey, true);

Here, $apiprivkey is the variable containing your private key.

  • 5) Convert the result from step 4 to a base 64 encoded string. Using PHP you can do

$encodedsignature = base64_encode($signature);

  • 6) Send this $encodedsignature variable with each request you make.

API Client tools will be available shortly in various programming languages that you can use to make calls quickly.

Rate Limits

The Atlantic.Net Cloud API allows clients to make a limited number of calls per given timeframe.

Present default rate limits are as follows:

Type Description Default
API Key calls are limited by your API Key 60/minute
Originating IP Address calls are limited by the IP Address your calls originate from 60/minute


If you require changes to these default limits, please contact support.

Error Messages

As mentioned above certain arguments are required for all API calls. When these arguments are not supplied, error messages can be expected. Please refer to the following table that delineates the possible error messages.

Code Message Explanation
E0001 API Key not supplied
E0002 API key/Signature is invalid
E0003 No Action has been specified
E0004 Signature has not been supplied
E0005 Action requested is not valid
E0006 Version requested is not valid
E0007 Timestamp was not supplied
E0008 Random identifier that was used in signature computation was not supplied
E0017 This is possibly a replay attack or a duplicate call. This request will be ignored.
E0020 API access for your account is currently deactivated. Normally, API access is deactivated by default. Please log into the web interface to activate your API access.
Retrieved from "http://knowledgebase.atlantic.net/index.php/API_Documentation"