# API

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 maszynach wirtualnych, 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 maszyn wirtualnych.

Do zbudowania API Oktawave została wykorzystana architektura REST (opens new window). 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ą.

Endpointy API w regionie PL1-WAW
https://pl1-api.oktawave.com/services (opens new window)	Services
https://pl1-api.oktawave.com/billing (opens new window)	Billing
https://pl1-api.oktawave.com/support (opens new window)	Support

Endpointy API w regionie PL2-KRK
https://pl2-api.oktawave.com/services (opens new window)	Services
https://pl2-api.oktawave.com/billing (opens new window)	Billing
https://pl2-api.oktawave.com/support (opens new window)	Support

Endpointy API wspólne dla obu regionów
https://account.oktawave.com/api (opens new window)	Account
https://status.oktawave.com/api (opens new window)	Oktawave Status Page
https://k44s-api.i.k44s.oktawave.com/api/ (opens new window)	Oktawave Kubernetes Service
https://odnsapi.oktawave.com (opens new window)	Oktawave Traffic Manager

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.

Uwaga! Testowane API działa na rzeczywistych danych konta

Definicja (deskryptor) API Oktawave oparta została na otwartym standardzie Open API zapoczątkowanym przez projekt swagger.io (opens new window). 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 (opens new window).

# Generowanie kodu klienta API dla języka Java

Skorzystanie z swagger-codegen (GitHub (opens new window)) 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.

Metody PUT i POST każdorazowo zwracają utworzony/aktualizowany 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 (opens new window). 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.

	2xx Success
200	OK. Powodzenie wykonania operacji.
201	Created. Kod operacji która kończy się utworzeniem i zwróceniem nowego zasobu.
204	No content. API przetworzyło żądanie ale nie zwróciło żadnej odpowiedzi. Wykorzystywane zazwyczaj w operacjach, które usuwają zasób. Może być również zwrócony przez URL zapytany o pusty zasób (np.: dane dostępowe do instancji, która nie była inicjalizowana).

	4xx Client Error
400	Bad request. Występuje w przypadku błędu walidacji żądania. Odpowiedź zawiera ModelState.
401	Unauthorized. Nieautoryzowany dostęp do API np. brak tokenu lub jest on nieprawidłowy.
402	Payment required. Szczególny przypadek błędu biznesowego. Brak środków na koncie do wykonania danej operacji.
403	Forbidden. Użytkownik nie ma uprawnień do wykonania danej operacji. Uwaga, ten kod może również wystąpić w sytuacji odwołania się do błędnego zasobu.
404	Not found. Zasób nie został znaleziony.
409	Conflict. Występuje w przypadku błędów biznesowych np. próba włączenia uruchomionej instancji. Odpowiedź zawiera ErrorCode.
429	Too Many Requests. Klient API wyczerpał limit dostępnych żądań do API w wybranej jednostce czasu.

	5xx Server Error
500	Internal server error. Nieobsłużone, niespodziewane błędy po stronie serwera.

Kod odpowiedzi inny niż 2xx oznacza, że zapytanie nie zostało prawidłowo przetworzone.

# Limit zapytań

API Oktawave posiada limit ilości obsługiwanych żądań dla każdego użytkownika, który standardowo wynosi 400 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.

API Oktawave obsługuje do 400 zapytań na minutę od każdego z użytkowników.

# 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 maszyny wirtualnej). 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 maszynie wirtualnej. 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
}