API REST jest natywnym API, udostępniającym pełen zakres funkcjonalności dostępnych z panelu klienta. Oparte jest o wywołania metody protokołu HTTP - GET, POST, PUT i DELETE w oparciu o odpowiednio przygotowany adres URL, nagłówki HTTP i opcjonalne parametry przekazywane w treści wywołania. Parametry przekazywane są w formacie JSON.
W zależności od wykonywanych działań, używane są następujące metody HTTP
| Metoda | Typ requestu |
|---|---|
| GET | Wywołania typu read-only, które służą do pobierania informacji o obiektach w systemie, np. listowanie wirtualnych maszyn |
| PUT | Wywołania tworzące nowy obiekt w systemie, np. wirtualną maszynę. |
| POST | Wywołania zmieniające stan istniejącego obiektu, np. włączanie wirtualnej maszyny. |
| DELETE | Wywołania usuwające obiekty z systemu, np. usuwanie wirtualnych maszyn. |
Każde wywołanie API musi zostać odpowiednio podpisane. Podpis zapewnia, że treść wywołania nie została zmieniona w trakcie przesyłania. Umożliwia także odrzucanie wywołań zbyt starych, które mogły stracić już aktualność lub zostać wysłane omyłkowo.
Podpisanie wywołania wymaga podania trzech nagłówków HTTP (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))
Przykład w PHP, generujący odpowiednie nagłówki
$API_KEY = 'id klucza'
$API_SECRET = 'wartosc klucza'
$API_METHOD = 'POST';
<nowiki>$API_URL = 'https://example.api.e24cloud.com/v2/test-method';</nowiki>
$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));
Informacje o odpowiedzi na zapytanie API znajdują się w nagłówkach odpowiedzi HTTP jak i w treści odpowiedzi. Treść odpowiedzi zwracana jest w formacie JSON. Nagłówki i budowa odpowiedzi zależą od rezultatu przetwarzania zapytania
| Kod odpowiedzi HTTP | Przyczyna | Treść odpowiedzi |
|---|---|---|
| 2xx | Zapytanie przetworzone poprawnie | {“success”: true, … inne pola, w zależności od zapytania} |
| 4xx | Nieprawidłowa sygnatura lub nieprawidłowe parametry | {“success”: false, “Errors”: { “Error”: { “Code”: 0, “Message”: “Komunikat błędu”}}} |
| 5xx | Wewnętrzny błąd serwera | Treść niezdefiniowana |