Getting started with the OpenvCloud Cloud API

Swagger UI

The Swagger UI of the Cloud API is available both in the End User Portal, and the System Portal as shown in Cloud API.

In the End User Portal click the Machine API in the top menu bar:

From there you can, for instance, click cloudapi__cloudspaces which expands all available API end points related to cloud spaces:

Clicking the POST /cloudapi/cloudspaces/create expands a form that allows you to create a cloud space:

Here's an example with some valid values:

And here's the result when you hit Try it out!:

From the command line

Two options:

JWT

Prerequirements:

  • Registrated user on ItsYou.online

  • OpenvCloud access rights for the ItsYou.online user

In order to get a JWT from ItsYou.online, you first need to create an application key for your ItsYou.online identity:

Copy the created Application ID and Secret into environment variables:

CLIENT_ID="G89h0YmCfjSFXvnbzrcNW_dY96Om"
CLIENT_SECRET="O5ALNpJkgAAr7Ado-exuGvTRfkpN"

Get the JWT from ItsYou.online:

JWT=$(curl -d 'grant_type=client_credentials&client_id='"$CLIENT_ID"'&client_secret='"$CLIENT_SECRET"'&response_type=id_token' https://itsyou.online/v1/oauth/access_token)

Get the accounts using the OpenvCloud Cloud API, passing the JWT in the header of the HTTPS request:

URL="https://dc-1.demo.greenitglobe.com"
curl -X POST -H 'Authorization: bearer '"$JWT" $URL/restmachine/cloudapi/accounts/list

Username and password

Set the username and password:

USER_NAME="..."
PASSWORD="..."

First get a session key from the Openvcloud Cloud API:

SESSION_KEY=$(curl -X POST -d 'username='"$USER_NAME"'&password='"$PASSWORD" $URL/restmachine/cloudapi/users/authenticate)

List all cloud spaces using the OpenvcCoud Cloud API, passing the session key in the authkey query string:

curl -X POST $URL/restmachine/cloudapi/cloudspaces/list?authkey=$SESSION_KEY

Using python

Make sure you've exported your client ID and secret:

export CLIENT_ID
export CLIENT_SECRET

In the interactive shell:

import os
import requests
params = {
'grant_type': 'client_credentials',
'response_type': 'id_token',
'client_id': os.environ['CLIENT_ID'],
'client_secret': os.environ['CLIENT_SECRET'],
'validity': 3600
}
url = 'https://itsyou.online/v1/oauth/access_token'
resp = requests.post(url, params=params)
resp.raise_for_status()
JWT = resp.content.decode('utf8')
headers = {'Authorization': 'bearer %s' % JWT}
url= "https://dc-1.demo.greenitglobe.com/restmachine/cloudapi/locations/getUrl"
resp = requests.post(url, headers=headers)

Using Portal client

If portal code is installed it is possible to use the portal client directly to connect to the OVC API:

pcl = j.clients.portal.getByInstance('main')
# List cloudspaces
pcl.actors.cloudapi.cloudspaces.list()

Calling the api asynchronously

Some API calls are long tasks and they can be blocking in certain cases. It is possible to call these functions asynchronously. This will return to the user the task guide of that call, which can then be polled to get the state of the job.

This is achieved by sending _async=True in the request body. An example using the second portal client which allows async calls:

pcl = j.clients.portal.getByInstance2("main")
task_guid = pcl.cloudapi.images.create(
name=name,
url=url,
gid=gid,
imagetype=type,
boottype=bootType,
username=username,
password=password,
accountId=accountId,
hotresize=hotResize,
_async=True,)
report = pcl.system.task.get(taskguid=task_guid)
# Report will return None until the task is completed.
# When finishing it will return a pair of [Bool, result]. Bool signifies success or failure of that call.
)

Or by using curl:

curl -X POST -H "Authorization: bearer {token}" -d '_async=True' https://dc-1.demo.greenitglobe.com/restmachine/cloudapi/cloudspaces/list
# Will return {taskguid}
curl -X POST -H "Authorization: bearer {token}" -d 'taskguid={taskguid}' https://dc-1.demo.greenitglobe.com/restmachine/system/task/get