Oktawave API

Search…
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​
Oktawave Status Page
​https://k44s-api.i.k44s.oktawave.com/api/​
Oktawave Kubernetes Service
​https://odnsapi.oktawave.com​
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. 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:
1
git clone https://github.com/swagger-api/swagger-codegen
2
cd swagger-codegen
3
mvn clean package
4
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar \
5
generate \
6
   -i https://api.oktawave.com/services/swagger/docs/v1 \
7
   -l java \
8
   -o ~/java_oktawave_api_client
Copied!
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. 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
1
{
2
  "date": "Mon, 11 Jul 2016 15:24:10 GMT",
3
  "content-type": "application/json; charset=utf-8",
4
  "content-length": "7628",
5
  "x-rate-limit-limit": "30",
6
  "x-rate-limit-remaining": "29",
7
  "x-rate-limit-reset": "55555.5302",
8
  "x-powered-by": "Oktawave, Oktawave",
9
  "server": "CERN httpd"
10
}
Copied!
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
1
curl -X GET 
2
--header 'Accept: application/json' 
3
--header 'Authorization: Bearer e6654d55a6345a269feefa717d055564' 
4
'https://api.oktawave.com/services/instances?query=okta&fields=id,name'
Copied!
Odpowiedź
1
{ 
2
    "Items": 
3
    [ 
4
        { 
5
            "Id": 12345, 
6
            "Name": "Oktawave API test" 
7
        }, 
8
        { 
9
            "Id": 12346, 
10
            "Name": "Oktawave API test 2" 
11
        } 
12
    ], 
13
    "Meta": 
14
    { 
15
        "Total": 2 
16
    } 
17
}
Copied!
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
1
{
2
    ...
3
    "Meta": { 
4
        "Total": 4
5
    }
6
}
Copied!
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
1
curl -X POST 
2
--header 'Accept: application/json' 
3
'https://api.oktawave.com/services/instances/12345/autoscaler/enable_ticket'
Copied!
Odpowiedź
1
{
2
  "Id": 12345,
3
  "CreationDate": "2016-07-11T09:20:40",
4
  "CreationUser": {
5
    "Id": 12345
6
  },
7
  "EndDate": null,
8
  "Status": {
9
    "Id": 12345,
10
    "Label": "Uruchomiona",
11
    ...
12
  },
13
  "OperationType": {
14
    "Id": 12345,
15
    "Label": "Aktualizacja ustawień Autoskalera",
16
    ...
17
  },
18
  "ObjectId": 12345,
19
  "ObjectType": {
20
    ...
21
    }
22
  },
23
  "Progress": 0
24
}
Copied!
Roadmap
Autoryzacja
Last modified 6mo ago
Copy link
Contents
Klient API
Żądania i odpowiedzi HTTP
Przykładowe nagłówki odpowiedzi
Filtrowanie
Metadane
Zlecenia