Z poziomu aplikacji korzystającej z API Oktawave możliwe do wykonania są wszystkie operacje, które użytkownik może wykonać bezpośrednio w panelu administracyjnym i są to m.in.:

• operacje wykonywane na instancjach, np. tworzenie, klonowanie i usuwanie,

• konfiguracja dysków i adresów IP instancji,

• migracja dysków pomiędzy regionami,

• zarządzanie usługami monitorującymi infrastrukturę,

• tworzenie prywatnych sieci w chmurze Oktawave,

• uruchamianie i zarządzanie szablonami instancji.

Do zbudowania API Oktawave została wykorzystana architektura REST. Każdy zasób posiada URL, metodę HTTP, nagłówki oraz model danych. Pełna lista zasobów jest dostępna wraz ze szczegółowym opisem w swaggerach podzielonym w zależności od części, której dotyczą.

API Oktawave jest bezstanowe. Każde żądanie do API zawiera w sobie wszystkie potrzebne informacje do jego obsłużenia. Aplikacja korzystająca z API każdorazowo otrzymuje ich aktualny stan w odpowiedzi serwera.

Klient API

Do wywołania zasobów API można użyć dowolnego narzędzia, które umożliwia komunikację po protokole HTTP (np. curl). Większość języków programowania posiada gotowe biblioteki do używania REST API. Aby przetestować API Oktawave można użyć udostępnionych przez Oktawave implementacji klienta Swagger. Po autoryzacji użytkownika można wywołać tam wszystkie zasoby, sprawdzić jak w czasie rzeczywistym odpowiada API i jak są zdefiniowane przykładowe żądania.

Definicja (deskryptor) API Oktawave oparta została na otwartym standardzie Open API zapoczątkowanym przez projekt swagger.io. Swagger to obecnie uznany standard w procesie tworzenia, dokumentowania i wdrażania rozwiązań API. Użycie otwartego rozwiązania pozwala naszym użytkownikom korzystać z szeregu narzędzi dostarczanych przez społeczność Swagger/Open API. Jednym z nich jest generator kodów źródłowych klienta API – swagger-codegen.

Generowanie kodu klienta API dla języka Java

Skorzystanie z swagger-codegen (GitHub) sprowadza się do wywołania następującej serii komend:

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar \
generate \
   -i https://api.oktawave.com/services/swagger/docs/v1 \
   -l java \
   -o ~/java_oktawave_api_client

Powyższe komendy wygenerują kod źródłowy klienta API Oktawave dla języka Java.

Żądania i odpowiedzi HTTP

Metody HTTP

API Oktawave używa następujących metod HTTP:

• GET - pobiera zasób,

• POST - tworzy nowy zasób lub wywołuje operację asynchroniczną i zwraca zlecenie,

• PUT - aktualizuje zasób,

• DELETE - usuwa zasób.

Odpowiedzi HTTP

Każde żądanie jest obsłużone przez serwer i wysyłana jest odpowiedź zgodnie ze zdefiniowanym modelem przypisanym do zasobu. Odpowiedź jest zwracana w formacie JSON lub XML w zależności od ustawienia nagłówka Accept w żądaniu (application/json, application/xml, text/jsoni text/xml). Poniżej lista podstawowych nagłówków przesyłanych w odpowiedzi przez serwer:

• Content-Type - format odpowiedzi,

• Content-Length - długość odpowiedzi,

• X-Rate-Limit-Limit - łączny limit zapytań nałożony na dane konto w wybranej jednostce czasu,

• X-Rate-Limit-Remaining - pozostały limit zapytań nałożony na dane konto w wybranej jednostce czasu,

• X-Rate-Limit-Reset - pozostały czas w milisekundach do zresetowania limitu.

Statusy HTTP

Po otrzymaniu odpowiedzi warto w pierwszej kolejności zweryfikować status HTTP. Kody podzielone są według specyfikacji HTTP. Status 2xx oznacza powodzenie operacji, 4xx oznacza błąd wynikający z danych żądania, oraz 5xx wysyłany w związku z błędami serwera. Pełna lista kodów jest przedstawiona w poniższej tabeli.

Limit zapytań

API Oktawave posiada limit ilości obsługiwanych żądań dla każdego użytkownika, który standardowo wynosi 180 zapytań na minutę. Jest to limit wystarczający dla skryptów uruchamiających wiele operacji jak również śledzących status wielu operacji równocześnie.

Przykładowe nagłówki odpowiedzi

{
  "date": "Mon, 11 Jul 2016 15:24:10 GMT",
  "content-type": "application/json; charset=utf-8",
  "content-length": "7628",
  "x-rate-limit-limit": "30",
  "x-rate-limit-remaining": "29",
  "x-rate-limit-reset": "55555.5302",
  "x-powered-by": "Oktawave, Oktawave",
  "server": "CERN httpd"
}

Filtrowanie

W przypadku zasobów GET możliwe jest filtrowanie zwracanych danych przez zapytanie. Służą do tego dwa parametry:

• fields - pozwala na przekazanie listy pól zasobu, które mają być zwrócone - wielkość liter jest ignorowana,

• query - przekazany ciąg znaków zostanie wyszukany w zawartości zasobu i zostaną zwrócone jedynie te spełniające zapytanie.

Żądanie

curl -X GET 
--header 'Accept: application/json' 
--header 'Authorization: Bearer e6654d55a6345a269feefa717d055564' 
'https://api.oktawave.com/services/instances?query=okta&fields=id,name'

Odpowiedź

{ 
    "Items": 
    [ 
        { 
            "Id": 12345, 
            "Name": "Oktawave API test" 
        }, 
        { 
            "Id": 12346, 
            "Name": "Oktawave API test 2" 
        } 
    ], 
    "Meta": 
    { 
        "Total": 2 
    } 
}

Metadane

Metody GET do których jest przekazywany konkretny identyfikator (ID) zwracają wybrany zasób. Z kolei wszystkie zasoby, do których nie jest przekazywany konkretny identyfikator (np. GET /instances) zwracają kolekcję do pierwszych 50 obiektów danego zasobu, wraz z dołączonymi metadanymi. Kolekcja spełnia dodatkowe funkcje:

• może przyjmować opcjonalne parametry pageSize - ustawia niestandardową liczbę obiektów na stronie oraz pageNumber - pozwala wybrać numer strony,

• metadane zawierają również pole total oznaczające liczbę wszystkich obiektów w kolekcji.

Przykład metadanych w kolekcji

{
    ...
    "Meta": { 
        "Total": 4
    }
}

Zlecenia

Wiele akcji, które można wywołać mają dłuższy czas oczekiwania wynikający ze specyfiki usługi (np. restart instancji). API nie może w takiej sytuacji od razu zwrócić wyniku operacji w odpowiedzi, nie może również trzymać otwartego połączenia do momentu zakończenia operacji.

Dlatego też wiele operacji wykonywanych jest asynchronicznie i w odpowiedzi zwracany jest jedynie identyfikator konkretnej operacji, czyli tzw. zlecenia. Zlecenie zawiera informacje pozwalające odpytywać API o aktualny status wykonywanej operacji.

Jednym z przykładów operacji, która zwraca zlecenie może być włączenie autoskalera na instancji. POST /instances/{id}/autoscaler/enable_ticket zwraca w odpowiedzi zlecenie.

Aby sprawdzić status operacji reprezentowanej przez zlecenie należy odpytać zasób GET /tickets/{id}. W odpowiedzi otrzymamy zlecenie zawierające dane takie jak:

• aktualny status operacji,

• typ operacji,

• postęp.

Żądanie

curl -X POST 
--header 'Accept: application/json' 
'https://api.oktawave.com/services/instances/12345/autoscaler/enable_ticket'

Odpowiedź

{
  "Id": 12345,
  "CreationDate": "2016-07-11T09:20:40",
  "CreationUser": {
    "Id": 12345
  },
  "EndDate": null,
  "Status": {
    "Id": 12345,
    "Label": "Uruchomiona",
    ...
  },
  "OperationType": {
    "Id": 12345,
    "Label": "Aktualizacja ustawień Autoskalera",
    ...
  },
  "ObjectId": 12345,
  "ObjectType": {
    ...
    }
  },
  "Progress": 0
}