vME APIs

Overview

vME's API allows you to programatically manage the vME instances and Docker engine.

All endpoints are authenticated according to the following headers schema:

{
  "username"  : "xxxxxx",  # your username 
  "api-key"   : "xxxxxx"   # your api-key
}

Pool Routes

Show all pools

GET /pool/show

AUTHENTICATIONS: headers

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
response = requests.get("https://1.23.45.67/pool/show", headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/pool/show"

Create a pool

POST /pool/create

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String
Name of pool to be created.
device
required
List List of device names.

Name	Type	Description
name required	String	Name of pool to be created.
device required	List	List of device names.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name"   : "vme-pool",
  "device" : ["nvme0n2", "nvme0n3"]
  }
response = requests.post("https://1.23.45.67/pool/create", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'vme-pool', 'device': ['nvme0n2', 'nvme0n3']}" \
  "https://1.23.45.67/pool/create"

Destroy a pool

DELETE /pool/destroy

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
  {
    "name" : "vme-pool"
  }
```
Name Type Description
name
required
String Name of pool to be destroyed.

Name	Type	Description
name required	String	Name of pool to be destroyed.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name" : "vme-pool"
  }
response = requests.delete("https://1.23.45.67/pool/destroy", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'vme-pool'}" \
  "https://1.23.45.67/pool/destroy"

Show current status of a pool

GET /pool/status

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
name
required
String The name of the pool to show status on.

Name	Type	Description
name required	String	The name of the pool to show status on.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "name" : "vme-pool"
}
response = requests.get("https://1.23.45.67/pool/status", params=params, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/pool/status?name=vme-pool"

Show history of a pool

GET /pool/history

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
name
required
String The name of the pool to run the history command on.

Name	Type	Description
name required	String	The name of the pool to run the history command on.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "name" : "vme-pool"
}
response = requests.get("https://1.23.45.67/pool/history", params=params headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/pool/history?name=vme-pool"

Register a pool

POST /pool/register

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String
The name of the pool to be registered.

Name	Type	Description
name required	String	The name of the pool to be registered.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {"name"   : "vme-pool"}
response = requests.post("https://1.23.45.67/pool/register", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'vme-pool'}" \
  "https://1.23.45.67/pool/register"

Source Routes

Show all sources

GET /source/show

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
pool_name
optional
String Name of pool, default is vme-pool.

Name	Type	Description
pool_name optional	String	Name of pool, default is `vme-pool`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "pool_name" : "vme-pool"
  }
response = requests.get("https://1.23.45.67/source/show", params=params, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/source/show?pool_name=vme-pool"

Create a source

POST /source/create

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

database method: container

{
  "pool_name"   : "vme-pool",
  "name"        : "foo",
  "quota"       : "1G",
  "compression" : "lzjb"
}

database method: network

{
  "pool_name" : "vme-pool",
  "name" : "foo",
  "compression" : "lzjb",
  "database_method" : "network",
  "network_info" : {
      "client_address" : "9.87.65.43",
      "anonuid" : 123,
      "anongid" : 123
  }
}

Name	Type	Description
name required	String	Name of source to be created.
pool_name required	String	Name of pool that contains a source.
dbtype optional	String	Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is `unknown`.
quota optional	String	A limit on the amount of disk space a dataset can consume, for example, `10G` for ten GB.
compression optional	String	Name of process where data is stored using less disk space, the name can be one of `on`, `off`, `lzjb`, `gzip`, `gzip-1`, `gzip-2`, `gzip-3`, `gzip-4`, `gzip-5`, `gzip-6`, `gzip-7`, `gzip-8`, `gzip-9`, `zle`, `lz4`, `False`, default is `False`.
database_method optional	String	Database method can be one of `container`, `network`, default is `container`.
network_info optional	Dictionary	Network information containing with `client_address`, `anonuid`, `anongid`. It is required when `database_method` was set to `network`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name" : "vme-pool",
  "name"      : "foo"
  }
response = requests.post("https://1.23.45.67/source/create", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d '{"pool_name": "vme-pool", "name": "foo"}' \
  "https://1.23.45.67/source/create"

Modify a source

POST /source/modify

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String Name of source to be modified.
pool_name
required
String Name of pool that contains a source.
property
required
Dictionary The properties of the source to be modified.

Name	Type	Description
name required	String	Name of source to be modified.
pool_name required	String	Name of pool that contains a source.
property required	Dictionary	The properties of the source to be modified.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name" : "vme-pool",
  "name"      : "foo",
  "property" : {
      "database_method" : "network",
      "quota" : "5G",
      "dbtype" : "mysql",
      "compression" : "gzip",
      "client_address" : "9.87.65.43"
      }
  }
response = requests.post("https://1.23.45.67/source/modify", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d '{"pool_name": "vme-pool", "name": "foo", "property" : {"database_method" : "network", "quota" : "5G", "dbtype" : "mysql", "compression" : "gzip", "client_address" : "9.87.65.43"}}' \
  "https://1.23.45.67/source/modify"

Rename a source

PUT /source/rename

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
    "pool_name"   : "vme-pool",
    "currentname" : "foo",
    "newname"     : "foofoo"
}
```
Name Type Description
pool_name
required
String Name of pool that contains a source.
currentname
required
String Name of source to be renamed.
newname
required
String New source name.

Name	Type	Description
pool_name required	String	Name of pool that contains a source.
currentname required	String	Name of source to be renamed.
newname required	String	New source name.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "currentname" : "foo",
  "newname"     : "foofoo"
  }
response = requests.put("https://1.23.45.67/source/rename", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'currentname': 'foo', 'newname': 'foofoo'}" \
  "https://1.23.45.67/source/rename"

Destroy a source

DELETE /source/destroy

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "pool_name" : "vme-pool",
  "source_name" : "foo"
}
```
Name Type Description
pool_name
required
String Name of pool that contains a source.
source_name
required
String Name of source to be destroyed.
recursive
optional
Boolean The recursive option, default is False.

Name	Type	Description
pool_name required	String	Name of pool that contains a source.
source_name required	String	Name of source to be destroyed.
recursive optional	Boolean	The recursive option, default is `False`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "source_name" : "foo"
  }
response = requests.delete("https://1.23.45.67/source/destroy", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo'}" \
  "https://1.23.45.67/source/destroy"

Snapshot Routes

Show all snapshots

GET /snapshot/show

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
pool_name
optional
String Name of pool.
source_name
optional
String Name of source/clone.

Name	Type	Description
pool_name optional	String	Name of pool.
source_name optional	String	Name of source/clone.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "pool_name" : "vme-pool"
  }
response = requests.get("https://1.23.45.67/snapshot/show", params=params, headers=headers)
if response.status_code < 200:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/snapshot/show?pool_name=vme-pool"

Create a sanpshot

POST /snapshot/create

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"   : "vme-pool",
  "source_name" : "foo",
  "name"        : "snap"
}

Name	Type	Description
pool_name required	String	Name of pool.
source_name required	String	Name of source/clone.
name required	String	Name of snapshot/bookmark to be created.
recursive optional	Boolean	Recursive option, default is `False`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "source_name" : "foo",
  "name"        : "snap"
  }
response = requests.post("https://1.23.45.67/snapshot/create", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo', 'name': 'snap'}" \
  "https://1.23.45.67/snapshot/create"

Rollback a snapshot

POST /snapshot/rollback

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap",
  "force"         : true
}

Name	Type	Description
pool_name required	String	Name of pool.
source_name required	String	Name of source/clone.
snapshot_name required	String	Name of snapshot/bookmark to be created.
force optional	Boolean	Force option to rollback, default is `False`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap",
  "force"         : True
  }
response = requests.post("https://1.23.45.67/snapshot/rollback", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo', 'name': 'snap'}" \
  "https://1.23.45.67/snapshot/rollback"

Rename a snapshot

PUT /snapshot/rename

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"   : "vme-pool",
  "source_name" : "foo",
  "currentname" : "snap",
  "newname"     : "snap-new"
}

Name	Type	Description
pool_name required	String	Name of pool.
source_name required	String	Name of source/clone.
currentname required	String	Name of snapshot/bookmark to be renamed.
newname required	String	New name of snapshot/bookmark.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "source_name" : "foo",
  "currentname" : "snap",
  "newname"     : "snap-new"
  }
response = requests.put("https://1.23.45.67/snapshot/rename", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo', 'currentname': 'snap', 'newname': 'snap-new'}" \
  "https://1.23.45.67/snapshot/rename"

Destroy a snapshot

DELETE /snapshot/destroy

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap"
}

Name	Type	Description
pool_name required	String	Name of pool.
source_name required	String	Name of source/clone.
snapshot_name required	String	Name of snapshot/bookmark to be destroyed.
recursive optional	Boolean	The recursive option, default is `False`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap"
  }
response = requests.delete("https://1.23.45.67/snapshot/destroy", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo', 'snapshot_name': 'snap'}" \
  "https://1.23.45.67/snapshot/destroy"

Clone Routes

Show all clones

GET /clone/show

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
pool_name
optional
String Name of pool.
source_name
optional
String Name of source.
snapshot_name
optional
String Name of snapshot.

Name	Type	Description
pool_name optional	String	Name of pool.
source_name optional	String	Name of source.
snapshot_name optional	String	Name of snapshot.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  'pool_name' : 'vme-pool'
  }
response = requests.get("https://1.23.45.67/clone/show", params=params, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H 'api-key: xxxx' \
  "https://1.23.45.67/clone/show?pool_name=vme-pool"

Create a clone

POST /clone/create

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap",
  "name"          : "foo-clone"
}

Name	Type	Description
pool_name required	String	Name of pool.
source_name required	String	Name of source.
snapshot_name required	String	Name of snapshot.
name required	String	Name of clone to be created.
dbtype optional	String	Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is `unknown`.
size optional	Integer	Number of clones (clonefarm) to be created, default is `1`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"     : "vme-pool",
  "source_name"   : "foo",
  "snapshot_name" : "snap",
  "name"          : "foo-clone"
  }
response = requests.post("https://1.23.45.67/clone/create", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'source_name': 'foo', 'snapshot_name': 'snap', 'name': 'foo-clone'}" \
  "https://1.23.45.67/clone/create"

Modify a clone

POST /clone/modify

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String Name of clone to be modified.
pool_name
required
String Name of pool that contains a source.
property
required
Dictionary The properties of the source to be modified.

Name	Type	Description
name required	String	Name of clone to be modified.
pool_name required	String	Name of pool that contains a source.
property required	Dictionary	The properties of the source to be modified.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name" : "vme-pool",
  "name"      : "foo-clone",
  "property" : {
      "database_method" : "network",
      "quota" : "5G",
      "dbtype" : "mysql",
      "compression" : "gzip",
      "client_address" : "9.87.65.43"
      }
  }
response = requests.post("https://1.23.45.67/clone/modify", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d '{"pool_name": "vme-pool", "name": "foo-clone", "property" : {"database_method" : "network", "quota" : "5G", "dbtype" : "mysql", "compression" : "gzip", "client_address" : "9.87.65.43"}}' \
  "https://1.23.45.67/clone/modify"

Rename a clone

PUT /clone/rename

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "pool_name"   : "vme-pool",
  "currentname" : "foo-clone",
  "newname"     : "foofoo-clone"
}
```
Name Type Description
pool_name
required
String Name of pool.
currentname
required
String Name of clone to be renamed.
newname
required
String New name of clone.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "currentname" : "foo-clone",
  "newname"     : "foofoo-clone"
  }
response = requests.put("https://1.23.45.67/clone/rename", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'currentname': 'foo-clone', 'newname': 'foofoo-clone'}" \
  "https://1.23.45.67/clone/rename"

Destroy a clone

DELETE /clone/destroy

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "pool_name"   : "vme-pool",
  "clone_name"  : "foo-clone"
}
```
Name Type Description
pool_name
required
String Name of pool.
clone_name
required
String Name of clone to be destroyed.
recursive
optional
Boolean The recursive option, default is False.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"   : "vme-pool",
  "clone_name"  : "foo-clone"
  }
response = requests.delete("https://1.23.45.67/clone/destroy", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'clone_name': 'foo-clone'}" \
  "https://1.23.45.67/clone/destroy"

Docker Image Routes

Pull an image

Similar to the docker pull command.

POST /docker/image/pull

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "repository" : "mysql",
  "tag"        : "8.4.0",
  "credential" : {"username":"","password":""}
}

Name	Type	Description
repository required	String	Name of image repository to be pulled.
tag optional	String	Name of tag, default is `latest`.
dbtype optional	String	Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is same as repository name.
credential optional	Dictionary	Information used to verify repository accession, default is `None`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "repository" : "mysql",
  }
response = requests.post("https://1.23.45.67/docker/image/pull", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'repository': 'mysql'}" \
  "https://1.23.45.67/docker/image/pull"

Register an image

POST /docker/image/register

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "name"   : "mysql:latest",
  "dbtype" : "mysql"
}

Name	Type	Description
name required	String	Name of image `name:tag` to be registered.
dbtype optional	String	Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is same as repository name.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name"   : "mysql:latest",
  "dbtype" : "mysql"
  }
response = requests.post("https://1.23.45.67/docker/image/register", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'mysql:latest', 'dbtype': 'mysql'}" \
  "https://1.23.45.67/docker/image/register"

List all images

Similar to the docker images command.

GET /docker/image/list

AUTHENTICATIONS: headers

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
response = requests.get("https://1.23.45.67/docker/image/list", headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/docker/image/list"

Save an image as .tar

POST /docker/image/save

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "image"    : "mysql:latest",
  "filename" : "myimage.tar"
}
```
Name Type Description
image
required
String Name of image name:tag to be saved.
filename
required
String Filename of saved image, the tar file will be saved at /home/vme/uploads.

Name	Type	Description
image required	String	Name of image `name:tag` to be saved.
filename required	String	Filename of saved image, the tar file will be saved at `/home/vme/uploads`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "image"    : "mysql:latest",
  "filename" : "myimage.tar"
  }
response = requests.post("https://1.23.45.67/docker/image/save", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'image': 'mysql:latest', 'filename': 'myimage.tar'}" \
  "https://1.23.45.67/docker/image/save"

Load an image from .tar

POST /docker/image/load

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "filename" : "myimage.tar"
}
```
Name Type Description
filename
required
String Filename of image to be loaded.

Name	Type	Description
filename required	String	Filename of image to be loaded.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "filename" : "myimage.tar"
  }
response = requests.post("https://1.23.45.67/docker/image/load", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'filename': 'myimage.tar'}" \
  "https://1.23.45.67/docker/image/load"

Remove an image

DELETE /docker/image/remove

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
  {
    "image" : "mysql:latest"
  }
```
Name Type Description
image
required
String Name of image name:tag to be removed.

Name	Type	Description
image required	String	Name of image `name:tag` to be removed.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "image" : "mysql:latest"
  }
response = requests.delete("https://1.23.45.67/docker/image/remove", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'image': 'mysql:latest'}" \
  "https://1.23.45.67/docker/image/remove"

Docker Container Routes

Create a container

Similar to the docker run command.

POST /docker/container/create

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "image"       : "mysql:latest", 
  "name"        : "foo-mysql", 
  "volumes"     : ["/vme-pool/sources/foo:/var/lib/mysql"],
  "ports"       : "8888:3306",
  "environment" : ["MYSQL_ROOT_PASSWORD=secret_password"]
}

Name	Type	Description
image required	String	Name of image.
name required	String	Name of container to be created.
detach optional	Boolean	Boolean for running container in the background, default is `True`.
command optional	String	Command to run in the container, default is `None`.
environment optional	List or Dictionary	Environment variables to set inside the container, as a dictionary or a list of strings in the format `["SOMEVARIABLE=xxx"]`, default is `None`.
volumes optional	List or Dictionary	Configure volumes mounted inside the container, default is `[]`.
ports optional	String	Ports to bind inside the container in the format `"a:b,c:d,..."`, for example `8080:80` means map port `8080` on the host to TCP port `80` in the container, default is `None`.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "image"       : "mysql:latest", 
  "name"        : "foo-mysql", 
  "volumes"     : ["/vme-pool/sources/foo:/var/lib/mysql"],
  "ports"       : "8888:3306",
  "environment" : ["MYSQL_ROOT_PASSWORD=secret_password"]
  }
response = requests.post("https://1.23.45.67/docker/container/create", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'image': 'mysql:latest', 'name': 'foo-mysql', 'volumes': ['/vme-pool/sources/foo:/var/lib/mysql'], 'ports': '8888:3306', 'environment' ['MYSQL_ROOT_PASSWORD=secret_password']}" \
  "https://1.23.45.67/docker/container/create"

List all containers

Similar to the docker ps -a command.

GET /docker/container/list

AUTHENTICATIONS: headers

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
response = requests.get("https://1.23.45.67/docker/container/list", headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/docker/container/list"

Start a container

Similar to the docker start command.

POST /docker/container/start

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String Name of container to be started.

Name	Type	Description
name required	String	Name of container to be started.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name" : "foo-mysql"
}
response = requests.post("https://1.23.45.67/docker/container/start", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'foo-mysql'}" \
  "https://1.23.45.67/docker/container/start"

Stop a container

Similar to the docker stop command.

POST /docker/container/stop

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
name
required
String Name of container to be stoped.

Name	Type	Description
name required	String	Name of container to be stoped.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name" : "foo-mysql"
}
response = requests.post("https://1.23.45.67/docker/container/stop", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'foo-mysql'}" \
  "https://1.23.45.67/docker/container/stop"

Execute command inside a container

Similar to the docker exec command.

POST /docker/container/exec

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "name"    : "foo-mysql",
  "command" : "mysql --user=root --password=\"secret_password\" -e \"show databases;\""
}
```
Name Type Description
name
required
String Name of container to be executed.
command
required
String or List Commands to be executed.

Name	Type	Description
name required	String	Name of container to be executed.
command required	String or List	Commands to be executed.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name"    : "foo-mysql",
  "command" : "mysql --user=root --password=\"secret_password\" -e \"show databases;\""
  }
response = requests.post("https://1.23.45.67/docker/container/exec", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'foo-mysql', 'command': 'mysql --user=root --password=\"secret_password\" -e \"show databases;\"'}" \
  "https://1.23.45.67/docker/container/exec"

Remove a container

Delete /docker/container/remove

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
  {
    "name" : "foo-mysql"
  }
```
Name Type Description
name
required
String Name of container to be removed.

Name	Type	Description
name required	String	Name of container to be removed.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "name" : "foo-mysql"
  }
response = requests.delete("https://1.23.45.67/docker/container/remove", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'name': 'foo-mysql'}" \
  "https://1.23.45.67/docker/container/remove"

Get a container log

GET /docker/container/log

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
name
required
String Name of container to get the log.

Name	Type	Description
name required	String	Name of container to get the log.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "name" : "foo-con"
}
response = requests.get("https://1.23.45.67/docker/container/log", params=params, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/docker/container/log?name=foo-con"

Get a container detail

GET /docker/container/detail

AUTHENTICATIONS: headers
QUERY PARAMETERS:

Name Type Description
name
required
String Name of container to get the detail.

Name	Type	Description
name required	String	Name of container to get the detail.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
params = {
  "name" : "foo-con"
}
response = requests.get("https://1.23.45.67/docker/container/detail", params=params, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/docker/container/detail?name=foo-con"

Database Routes

Connect to database

POST /db/connect

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:
```
{
  "dbtype"   : "mysql",
  "host"     : "localhost",
  "user"     : "root",
  "password" : "secret_password",
  "port"     : 8888
}
```
The body is the required credential information, the general formatting is {"dbtype": "<database_type>", "host": "<host>", "user": "<user>", "password": "<password>", "port": "<port>"}.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
credential = {
  "dbtype"   : "mysql",
  "host"     : "localhost",
  "user"     : "root",
  "password" : "secret_password",
  "port"     : 8888
  }
response = requests.post("https://1.23.45.67/db/connect", json=credentail, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'dbtype': 'mysql', 'host': 'localhost', 'user': 'root', 'password': ''secret_password, 'port': 8888}" \
  "https://1.23.45.67/db/connect"

Receive database

Receive backup and restore dataset.

POST /db/receive

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

{
  "pool_name"    : "vme-pool",
  "dataset_name" : "restored-sender-from-backup",
  "dbtype"       : "mysql",
  "src"          : "demo-pool-sources-sender@now-20230829183552.vmebk"
}

Name	Type	Description
pool_name required	String	Name of pool.
dataset_name required	String	Name of dataset to be restored.
dbtype optional	String	Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is `unknown`.
src required	String	Path name of received backup file in `.vmebk` format, the default absolute path is `/enov8/vme/data/<filename>` when only the filename is provided.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "pool_name"    : "vme-pool",
  "dataset_name" : "restored-sender-from-backup",
  "src"          : "demo-pool-sources-sender@now-20230829183552.vmebk"
  }
response = requests.post("https://1.23.45.67/db/receive", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'pool_name': 'vme-pool', 'dataset_name': 'restored-sender-from-backup', 'src': 'demo-pool-sources-sender@now-20230829183552.vmebk'}" \
  "https://1.23.45.67/db/receive"

Send database

POST /db/send

AUTHENTICATIONS: headers

REQUEST BODY SCHEMA:

pool2pool

{
  "type"      : "pool2pool",
  "dataset"   : "demo-pool/sources/sender@now",
  "receiver"  : {
      "pool_name"    : "vme-pool",
      "dataset_name" : "receiver-snap"
  }
}

sys2sys

{
  "type"     : "sys2sys",
  "dataset"  : "demo-pool/sources/sender@now",
  "receiver" : {
      "address"       : "https://9.87.654.321",
      "username"      : "admin",
      "identity_file" : "/home/vme/uploads/key.pem",
      "api-key"       : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "pool_name"     : "vme-pool",
      "dataset_name"  : "receiver-sys2sys-snap"
  }
}

Name	Type	Description
type required	String	Sending type, `pool2pool` or `sys2sys`.
dataset required	String	Name of dataset to be send.
receiver required	Dictionary	Information of receiver contains `pool_name`, `dataset_name`, and other verification info for receiver.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "type"     : "pool2pool",
  "dataset"  : "demo-pool/sources/sender@now",
  "receiver" : {
      "pool_name"    : "vme-pool",
      "dataset_name" : "receiver-snap"
    }
  }
response = requests.post("https://1.23.45.67/db/send", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'type': 'pool2pool', 'dataset': 'demo-pool/sources/sender@now', 'receiver': {'pool_name': 'vme-pool', 'dataset_name': 'receiver-snap'}}" \
  "https://1.23.45.67/db/send"

Backup database

Get all backup filenames.

GET /db/backup

AUTHENTICATIONS: headers

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
response = requests.get("https://1.23.45.67/db/backup", headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X GET \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  "https://1.23.45.67/db/backup"

Create backup file.

POST /db/backup

AUTHENTICATIONS: headers
REQUEST BODY SCHEMA:

Name Type Description
dataset
required
String Name of dataset to be backup.

Name	Type	Description
dataset required	String	Name of dataset to be backup.

EXAMPLE:

Python
Curl

# Download the requests library from https://docs.python-requests.org/en/latest/
import requests
body = {
  "dataset" : "vme-pool/sources/foo"
  }
response = requests.post("https://1.23.45.67/db/backup", json=body, headers=headers)
if response.status_code < 500:
  print(response.json())

curl -X POST \
  -H "Content-Type: application/json" \
  -H "username: xxxxx" \
  -H "api-key: xxxxx" \
  -d "{'dataset' : 'vme-pool/sources/foo'}" \
  "https://1.23.45.67/db/backup"

API Examples (Postman Collection)

Click here to download the Postman collection with example requests for various vME API requests.

note

If you're unsure how to import the collection into Postman, please refer to the Postman documentation for a step-by-step guide on importing collection.

vME APIs

Overview​

Pool Routes​

Show all pools​

Create a pool​

Destroy a pool​

Show current status of a pool​

Show history of a pool​

Register a pool​

Source Routes​

Show all sources​

Create a source​

Modify a source​

Rename a source​

Destroy a source​

Snapshot Routes​

Show all snapshots​

Create a sanpshot​

Rollback a snapshot​

Rename a snapshot​

Destroy a snapshot​

Clone Routes​

Show all clones​

Create a clone​

Modify a clone​

Rename a clone​

Destroy a clone​

Docker Image Routes​

Pull an image​

Register an image​

List all images​

Save an image as .tar​

Load an image from .tar​

Remove an image​

Docker Container Routes​

Create a container​

List all containers​

Start a container​

Stop a container​

Execute command inside a container​

Remove a container​

Get a container log​

Get a container detail​

Database Routes​

Connect to database​

Receive database​

Send database​

Backup database​

API Examples (Postman Collection)​

Overview

Pool Routes

Show all pools

Create a pool

Destroy a pool

Show current status of a pool

Show history of a pool

Register a pool

Source Routes

Show all sources

Create a source

Modify a source

Rename a source

Destroy a source

Snapshot Routes

Show all snapshots

Create a sanpshot

Rollback a snapshot

Rename a snapshot

Destroy a snapshot

Clone Routes

Show all clones

Create a clone

Modify a clone

Rename a clone

Destroy a clone

Docker Image Routes

Pull an image

Register an image

List all images

Save an image as .tar

Load an image from .tar

Remove an image

Docker Container Routes

Create a container

List all containers

Start a container

Stop a container

Execute command inside a container

Remove a container

Get a container log

Get a container detail

Database Routes

Connect to database

Receive database

Send database

Backup database

API Examples (Postman Collection)