An Introduction To Virtualize API Usage

Introduction

DATPROF Virtualize is orchestrated entirely from within DATPROF Runtime. This means that all of its core functionality can also be called by using our REST API, for administrators and end-user who want to automate the deployment, cloning, snapshotting and monitoring of virtualized database environments. This page gives insights into some of the more common API calls and actions users can be expected to perform through the API. For a full overview of the API specification, the user can navigate to the automatically generated API specification within Runtime by using the API Docs link in the bottom-left corner of the user interface.

Where possible we’ll rely on PowerShell to execute our commands.

This page uses some variables which are pulled from other parts of Runtime. This means that if you’d like to reproduce these, you’ll need to have a basic understanding of the Runtime API itself, which is described in the Runtime manual.

Container Hosts

Collecting information about existing container hosts

To collect information about container hosts, supplying variables is not necessary. We only need to adjust the URI of our base API call.

Variable Name	Explanation
ID	This is the container host ID of the container, which is used to collect information about the container host through the API. In other calls, this is referred to as containerHostId.
name	The name of the container host, as supplied by the user.
host	The host name or IP-address of the container host.
port	The port over which traffic to and from the container host travels.
isConfigured	The isConfigured value indicates whether the initial setup steps performed during the adding of a container host have been completed. Generally, this value will always be returned as True from this API call.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/hosts' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/hosts' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

Output

Variable Name	Explanation
id	This is the container host ID of the container, which is used to collect information about the container host through the API. In other calls, this is referred to as containerHostId.
name	The name of the image
image	The host name or IP-address of the container host.
state	The port over which traffic to and from the container host travels.
created	The isConfigured value indicates whether the initial setup steps performed during the adding of a container host have been completed. Generally, this value will always be returned as True from this API call.

Creating a new container host

In order to create a new container host, a valid base Virtualize VM must be running and accessible over either your local network if hosted locally, or externally if the VM is hosted in, for example, the cloud. To do this, the user must supply the following values in the request’s body:

The name value, which indicates which name the container host will get after creation.
A valid host value which contains either the VM’s IP-address, or a valid host-name that redirects to the virtual machine.
The port over which communication to the VM can be done. By default this is port 2376 when using DATPROF’s Virtualize VM image.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'
$body = @"
{
      `"name`": `"<container_host_name>`",
      `"host`": `"<ip_or_host_name>`",
      `"port`": `"<container port>`"
}
"@
 Invoke-WebRequest $runtimeURL'/api/2/virtualize/hosts' -Method POST -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '900c568e-0ad6-4a51-bbef-65e3e1d8df7a'
$body = @"
{
      `"name`": `"SampleContainerHost`",
      `"host`": `"datprof-vm`",
      `"port`": `"2376`"
}
"@
 Invoke-WebRequest $runtimeURL'/api/2/virtualize/hosts' -Method POST -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

Uploading container images to the container host

In order to start working with Virtualize, we need to upload container images for the database types we want to work with. For this call, we’ll need the ContainerHostId, and the file we want to upload. For this call, we’ll use Curl, as this handles files a bit more easily than PowerShell, and allows us to supply a file without needing to convert it into binary first. First, we’ll look into how to get out container image files.

In order to execute curl through PowerShell, simply input curl.exe at the start of your command.

Saving a docker image as a file

Normally, when using Docker, users make use of the docker pull command to store an image in something like the Docker Desktop application. For our use-case, we’ll need to have this available as a separate file on the file system. We can do this by exporting the image from Docker by using the docker save command. Here’s a quick overview on how to do this on Windows command-line:

Docker Syntax

CODE

Docker pull <image_name>

docker save <image_name> -o "<output_file_directory_and_name>"

Docker Example

CODE

Docker pull postgres

docker save postgres -o "C:\temp\postgres.image"

Uploading the container image

Now that we have a file on the filesystem, we can upload it to the Container host.

Curl syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

$file = 'C:\temp\my.image' 
curl.exe -F file=@"$file"  --header "X-auth-token: $apikey"  $runtimeURL'/api/2/virtualize/hosts/<ContainerHostId>/images'  -X POST -s | ConvertFrom-Json

Curl example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

$file = 'C:\temp\my.image' 
curl.exe -F file=@"$file"  --header "X-auth-token: $apikey"  $runtimeURL'/api/2/virtualize/hosts/1/images'  -X POST -s | ConvertFrom-Json

Listing existing container images

In order to view which container images are present, it’s possible to use the List images on the container host, and query a list of the available images on the container host. For this call the only input needed is the ContainerHostId.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/hosts/<ContainerHostId>/containers' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/hosts/1/containers' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

Manipulating Containers

When manipulating containers (starting, stopping, etc), there are two variants for each API call. One uses a combination of the containerHostId and the containerName, and one uses the EnvironmentId of the environment the container is attached to. For the below examples, the EnvironmentId version is used.

Starting a container

In order to start a container, we only need the EnvironmentID of the environment the container is attached to.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/environment/start/<environment_id>' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/environment/start/32' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

Stopping a container

Much like starting a container, we only need the EnvironmentID of the environment the container is attached to.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/environment/stop/<environment_id>' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/environment/stop/32' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

Cloning

Cloning virtualized database environments

In order to clone a virtualized environment, we need to know the original environment’s environmentId, as well as the port mapping for the new environment and a name for the new environment. We can figure out the port mapping by using the Clone Information call.

Collecting clone information

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/environment/clone/<environment_id>' -Method 'GET'  -Headers @{"X-Auth-Token"="$apiKey"} | ConvertTo-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '900c568e-0ad6-4a51-bbef-65e3e1d8df7a'
Invoke-WebReqiest -Uri $runtimeUrl'/api/2/virtualize/environment/clone/14' -Method 'GET'  -Headers @{"X-Auth-Token"="$apiKey"} | ConvertTo-Json

Output

Variable Name

Explanation

previousName

This is the name of the current environment, as determined by the EnvironmentId provided

usedPorts

A list of all the port numbers already used by containers based on the original

portMapping

This is a nested object which contains the following:

host: the port number used by the host, and also the port number the user should modify when cloning the container.
container: the port number used by the container. In most cases, this is static.
protocol: which network protocol is used to facilitate network communication (TCP or UDP)

Creating a new cloned environment

In order to create a new cloned environment, we need to supply some of the information pulled from the Clone Information call (the port mapping of our old container, and the protocol network protocol used). Aside from that, we just need to have the EnvironmentId of the environment we want to clone.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'
$body = @"
{
  `"portMappings`": [ {
      `"host`": `"<new_port_number>`",
      `"container`": `"<container_port_number>`",
      `"protocol`": `"TCP`"
    } ],
  `"environmentName`": `"API_EXAMPLE`"
}
"@

$response = Invoke-RestMethod 'http://localhost:7070/api/2/virtualize/environment/clone/<environment_id>' -Method 'POST' -Headers @{"X-Auth-Token"="$apiKey"} -Body $body
$response | ConvertTo-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '900c568e-0ad6-4a51-bbef-65e3e1d8df7a'
$body = @"
{
  `"portMappings`": [ {
      `"host`": `"5512`",
      `"container`": `"5432`",
      `"protocol`": `"TCP`"
    } ],
  `"environmentName`": `"API_EXAMPLE`"
}
"@

$response = Invoke-RestMethod 'http://localhost:7070/api/2/virtualize/environment/clone/14' -Method 'POST' -Headers @{"X-Auth-Token"="$apiKey"} -Body $body
$response | ConvertTo-Json

Output

This call only returns a single integer; the EnvironmentId of the new clone, which is now referred to as a virtualized environment. To get more information about this new environment, execute the Clone Information call, using the newly generated ID.

Deleting a cloned environment

In order to delete a cloned environment, the regular API call to remove an environment can be used.

Snapshotting

Snapshotting virtualized database environments

One benefit of environments being virtualized is that these can be easily snapshotted and restored from either the Runtime UI, or the REST API. To illustrate the functionality, this chapter includes the following steps:

Listing existing snapshots for a virtualized environment
Creating a new snapshot
Restoring to a specific snapshot
Removing snapshots

Listing existing snapshots for an environment

To retrieve a list of snapshots, we use the Retrieve a list of all available snapshots call. To execute this, the only variable needed is the EnvironmentId of the environment we’d like to use.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/snapshot/<EnvironmentId>' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/snapshot/14' -Headers @{"X-Auth-Token"="$apiKey"} -Method GET -ContentType "application/json" | ConvertFrom-Json

Output

Variable Name

Explanation

id

The id for a snapshots consists of a pair of values:

createdBy, which is the id of the user who created the snapshot
The name of the snapshot. This is returned as the timestamp on which the snapshot was originally created.

These are returned together in JSON format.

createdBy

The UserId of the user who created this snapshot.

created

The timestamp on which the snapshot was originally created (Ex. 2024-09-02T09:30:49Z).

Creating a new snapshot

To create a new snapshot, we use the Creates a new snapshot, returns the created snapshot call. This only requires the EnvironmentId of the environment we’d like to create a new snapshot for.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/snapshot/<environment_id>' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

Powershell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '83d0c41e-0c76-41e9-a6e1-51ba150f73f2'

Invoke-WebRequest -Uri $runtimeUrl'/api/2/virtualize/snapshot/14' -Headers @{"X-Auth-Token"="$apiKey"} -Method POST -ContentType "application/json" | ConvertFrom-Json

Deleting a snapshot

The request body for deleting a snapshot is a bit more complex, as this requires the id of the snapshot, which is a itself a pair of the createdBy value and the timestamp on which the container was created. The easiest way to obtain this is to use the Retrieve a list of all available snapshots call, and copy over the id. On top of this, we need the EnvironmentId of the environment the snapshot is attached to.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'
$body = @"
{
      `"createdBy`"=`"<createdBy>`",
      `"name`"=`"<creation_timestamp>`"
}
"@
Invoke-WebRequest $runtimeURL'/api/2/virtualize/snapshot/<environment_id>' -Method DELETE -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '900c568e-0ad6-4a51-bbef-65e3e1d8df7a'
$body = @"
{
      `"createdBy`"=`"1`",
      `"name`"=`"2024-12-16T09:00:49.679523300Z`"
}
"@
Invoke-WebRequest $runtimeURL'/api/2/virtualize/snapshot/14' -Method DELETE -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

Output

The only output for this call is the HTTP status code for the call. If this is 200, the action was successful.

Restoring from a snapshot

In order to restore from a snapshot, we’ll need the same information as in the Deleting a snapshot chapter.

PowerShell Syntax

CODE

$runtimeURL = '<your_runtime_url_here>'
$apikey = '<your_API_key_here>'
$body = @"
{
      `"createdBy`"=`"<createdBy>`",
      `"name`"=`"<creation_timestamp>`"
}
"@
Invoke-WebRequest $runtimeURL'/api/2/virtualize/snapshot/<environment_id>/restore' -Method POST -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

PowerShell Example

CODE

$runtimeURL = 'http://localhost:7070'
$apikey = '900c568e-0ad6-4a51-bbef-65e3e1d8df7a'
$body = @"
{
      `"createdBy`"=`"1`",
      `"name`"=`"2024-09-02T08:11:57.861092200Z`"
}
"@
 Invoke-WebRequest $runtimeURL'/api/2/virtualize/snapshot/14/restore' -Method POST -Headers @{"X-Auth-Token"="$apiKey"} -Body $body -ContentType "Application/json"

Output

The only output for this call is the HTTP status code for the call. If this is 200, the action was successful.

Introduction

Table of Contents

Container Hosts

Collecting information about existing container hosts

PowerShell Syntax

PowerShell Example

Output

Creating a new container host

PowerShell Syntax

PowerShell Example

Uploading container images to the container host

Saving a docker image as a file

Docker Syntax

Docker Example

Uploading the container image

Curl syntax

Curl example

Listing existing container images

PowerShell Syntax

PowerShell Example

Manipulating Containers

Starting a container

PowerShell Syntax

PowerShell Example

Stopping a container

PowerShell Syntax

PowerShell Example

Cloning

Cloning virtualized database environments

Collecting clone information

PowerShell Syntax

PowerShell Example

Output

Creating a new cloned environment

PowerShell Syntax

PowerShell Example

Output

Deleting a cloned environment

Snapshotting

Snapshotting virtualized database environments

Listing existing snapshots for an environment

PowerShell Syntax

PowerShell Example

Output

Creating a new snapshot

PowerShell Syntax

Powershell Example

Deleting a snapshot

PowerShell Syntax

PowerShell Example

Output

Restoring from a snapshot

PowerShell Syntax

PowerShell Example

Output