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.
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. |
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):
application/json
$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));
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 |