Oktawave API

API Oktawave jest usługą umożliwiającą wszystkim użytkownikom platformy zarządzanie zasobami chmury za pomocą zewnętrznych narzędzi. Za pośrednictwem API zlecisz te same operacje co w Panelu.

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ą.

Endpointy API w regionie PL1-WAW

https://pl1-api.oktawave.com/services

Services

https://pl1-api.oktawave.com/billing

Billing

https://pl1-api.oktawave.com/support

Support

Endpointy API w regionie PL2-KRK

https://pl2-api.oktawave.com/services

Services

https://pl2-api.oktawave.com/billing

Billing

https://pl2-api.oktawave.com/support

Support

Endpointy API wspólne dla obu regionów

https://account.oktawave.com/api

Account

https://status.oktawave.com/api

Status

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

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/jsontext/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.

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

API Oktawave obsługuje do 180 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 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
}