API kompatybilne z REST

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.

Metody HTTP

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ące obiektu, np włączanie wirtualnej maszyny.
DELETE Wywołania usuwające obiekty z systemu, np. usuwanie wirtualnych maszyn.

Podpisywanie wywołań

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ść, a zostać wysłane omyłkowo.

Podpisanie wywołania wymaga podania trzech nagłówków HTTP:

  • “Content-Type” - ustawiony na application/json
  • “X-Date” - data generacji wywołania, w formacie RFC 1123 (np. Mon, 04 Jul 2015, 14:01:02 EST)
  • “Authorization” - wartość wygenerowana według poniższego algorytmu
$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 = 'http://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));

Odpowiedzi

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 zaleznosci 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