API compatible with REST

What is a REST API?

The REST API is a native API, providing a full range of functionality accessible from the client panel. It is based on HTTP protocol method calls - GET, POST, PUT and DELETE based on a properly prepared URL, HTTP headers and optional parameters passed in the body of the call. The parameters are passed in JSON format.

HTTP methods in the REST API

Depending on the activities performed, the following HTTP methods are used

Method Request type
GET Read-only calls that are used to retrieve information about objects in the system, e.g., listing virtual machines.
PUT Calls that create a new object in the system, such as a virtual machine.
POST Calls that change the state of an existing object, such as enabling a virtual machine.
DELETE Calls removing objects from the system, e.g., removing virtual machines.


Signing API calls - HTTP headers

Each API call must be properly signed. The signature ensures that the content of the call have not been changed during transmission. It also makes it possible to discard calls that are too old, which may have already expired and been sent in error.

Signing a call requires three HTTP headers (HTTP request header):

  • “Content-Type” - set to application/json
  • “X-Date” - call generation date, in RFC 1123 format (eg. Mon, 04 Jul 2015, 14:01:02 EST)
  • “Authorization” - value generated by the following algorithm
$request = $HTTP_METHOD + "\n" + $HTTP_HOST + "\n" + $HEADER[X-Date] + "\n" + $URI_PATH + $QUERY_STRING + "\n" + $REQUEST_BODY
Authorization: $API_KEY + ':' + base64(hmac_sha256($request, $API_SECRET))

An example in PHP, generating the appropriate headers

$API_KEY = 'key id'
$API_SECRET = 'key secret'
$API_METHOD = 'POST';
$API_URL = 'https://example.api.e24cloud.com/v2/test-method';

$headerDate = gmdate('D, d M Y H:i:s T');
$requestHeader = array(
 'Content-Type: application/json',
 'X-Date: ' . $headerDate
);

$parsedUrl = parse_url($API_URL);
$signString = $API_METHOD . "\n";
$signString .= $parsedUrl['host'] . "\n";
$signString .= $headerDate . "\n";
$signString .= $parsedUrl['path'] . (isset($parsedUrl['query']) && $parsedUrl['query'] ? '?' . $parsedUrl['query'] : "") . "\n";
$signString .= $requestData ? $requestData : "";

$requestHeader[] = 'Authorization: ' . $API_KEY . ':' . base64_encode(hash_hmac('SHA256', $signString, $API_SECRET, true));

Responses from the REST API - code, reason and content of the response

Information about the response to an API request can be found in the HTTP response headers as well as in the body of the response. The response body is returned in JSON format. Response headers and structure depend on the result of query processing

HTTP Response Code Reason Response Content
2xx Query processed correctly {“success”: true, … various fields, depending on the query }
4xx Invalid signature or invalid parameters {“success”: false, “Errors”: { “Error”: { “Code”: 0, “Message”: “Error message”}}}
5xx Internal server error Content undefined