CERN Unified Storage API API Reference

A unified storage API for all data-storage back-ends.

Version: 2.0.1

default

Default namespace

/

Storage operations

/

GET /{subsystem}/export

Get all ACLs present on the back-end

X-Fields

An optional fields mask

type
string (mask)
in
header
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
Export Policy

The full policy

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

Response Example (200 OK) 
[
  {
    "name": "allow_cluster_x",
    "rules": [
      "10.10.10.1/24"
    ]
  }
]
sso read , write
/

DELETE /{subsystem}/export/{policy}

Delete the entire policy

policy

The policy to operate on

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
204 No Content

Successfully deleted the policy

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

404 Not Found

No such policy exists
sso read , write
/

GET /{subsystem}/export/{policy}

Display the rules of a given policy

X-Fields

An optional fields mask

type
string (mask)
in
header
policy

The policy to operate on

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
Export Policy

Get the rules of a specific policy

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

Response Example (200 OK) 
{
  "name": "allow_cluster_x",
  "rules": [
    "10.10.10.1/24"
  ]
}
sso read , write
/

POST /{subsystem}/export/{policy}

Grant hosts matching a given pattern access to the given volume

PolicyRule
undefined
policy

The policy to operate on

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
Request Example
{
  "rules": [
    "10.10.10.1/24"
  ]
}
201 Created

The provided access rules were added

400 Bad Request

A policy with that name already exists

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'
sso read , write
/

DELETE /{subsystem}/export/{policy}/{rule}

Delete rule from policy

rule

The policy rule to operate on

type
string
in
path
policy

The policy to operate on

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
204 No Content

Successfully deleted the rule, or rule did not exist

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

404 Not Found

No such policy exists
sso read , write
/

PUT /{subsystem}/export/{policy}/{rule}

Grant hosts matching a given pattern access

rule

The policy rule to operate on

type
string
in
path
policy

The policy to operate on

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
201 Created

The provided access rule was added or already present

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'
sso read , write
/

GET /{subsystem}/volumes

Get a list of all volumes

X-Fields

An optional fields mask

type
string (mask)
in
header
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
VolumeRead

Success

403 Forbidden

Current user is not logged in or not a member of the role 'USER_ROLE'

Response Example (200 OK) 
[
  {
    "creation_time": "string (date-time)",
    "filer_address": "string",
    "percentage_snapshot_reserve_used": "integer",
    "size_used": "integer",
    "state": "string",
    "uuid": "string",
    "aggregate_name": "string",
    "junction_path": "string",
    "name": "volume_name",
    "size_total": "integer",
    "active_policy_name": "string",
    "autosize_enabled": "boolean",
    "autosize_increment": "integer",
    "caching_policy": "string",
    "compression_enabled": "boolean",
    "inline_compression": "boolean",
    "max_autosize": "integer",
    "percentage_snapshot_reserve": "integer"
  }
]
sso read , write
/

DELETE /{subsystem}/volumes/{volume_name}

Restrict the volume named volume_name but do not actually delete it

volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
204 No Content

Successfully restricted

403 Forbidden

Current user is not logged in or not a member of the role 'UBER_ADMIN_ROLE'
sso read , write
/

GET /{subsystem}/volumes/{volume_name}

Get a specific volume by name

X-Fields

An optional fields mask

type
string (mask)
in
header
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
VolumeRead

The volume named volume_name

201 Created

A new volume was created

403 Forbidden

Current user is not logged in or not a member of the role 'USER_ROLE'

404 Not Found

No such volume exists

Response Example (200 OK) 
{
  "creation_time": "string (date-time)",
  "filer_address": "string",
  "percentage_snapshot_reserve_used": "integer",
  "size_used": "integer",
  "state": "string",
  "uuid": "string",
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}
sso read , write
/

PATCH /{subsystem}/volumes/{volume_name}

Partially update volume_name

VolumeWrite
undefined
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
Request Example
{
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}
403 Forbidden

Current user is not logged in or not a member of the role 'UBER_ADMIN_ROLE'
sso read , write
/

POST /{subsystem}/volumes/{volume_name}

Create a new volume with the given details. If from_snapshot is a snapshot and volume_name already refers to an existing volume, roll back that volume to that snapshot. If from_snapshot is a snapshot, from_volume is an existing volume and volume_name doesn't already exist, create a clone of from_volume named volume_name, in the state at from_snapshot.

OptionalFromSnapshot
undefined
X-Fields

An optional fields mask

type
string (mask)
in
header
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
Request Example
{
  "from_snapshot": "string",
  "from_volume": "string",
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}
200 OK
VolumeRead

The newly created volume (if created), otherwise nothing

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

Response Example (200 OK) 
{
  "creation_time": "string (date-time)",
  "filer_address": "string",
  "percentage_snapshot_reserve_used": "integer",
  "size_used": "integer",
  "state": "string",
  "uuid": "string",
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}
sso read , write
/

GET /{subsystem}/volumes/{volume_name}/locks

Get the host locking the volume, if any

X-Fields

An optional fields mask

type
string (mask)
in
header
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
Lock

An empty list (if no locks were held) or a single dict describing the host holding the lock

403 Forbidden

Current user is not logged in or not a member of the role 'USER_ROLE'

Response Example (200 OK) 
[
  {
    "host": "dbthing.cern.ch"
  }
]
sso read , write
/

DELETE /{subsystem}/volumes/{volume_name}/locks/{host}

Force the lock for the host

volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
host

the host holding the lock in question

type
string
in
path
204 No Content

Lock successfully forced

403 Forbidden

Current user is not logged in or not a member of the role 'UBER_ADMIN_ROLE'
sso read , write
/

PUT /{subsystem}/volumes/{volume_name}/locks/{host}

Lock the volume with host holding the lock

volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
host

the host holding the lock in question

type
string
in
path
201 Created

A new lock was added

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'
sso read , write
/

GET /{subsystem}/volumes/{volume_name}/snapshots

X-Fields

An optional fields mask

type
string (mask)
in
header
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
Snapshot

All snapshots for the volume

Response Example (200 OK) 
[
  {
    "name": "string"
  }
]
/

DELETE /{subsystem}/volumes/{volume_name}/snapshots/{snapshot_name}

Delete the snapshot

volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
snapshot_name

The snapshot name

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
204 No Content

Successfully deleted

403 Forbidden

Current user is not logged in or not a member of the role 'ADMIN_ROLE'

404 Not Found

No such snapshot
sso read , write
/

GET /{subsystem}/volumes/{volume_name}/snapshots/{snapshot_name}

Get the current information for a given snapshot

X-Fields

An optional fields mask

type
string (mask)
in
header
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
snapshot_name

The snapshot name

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
200 OK
Snapshot

Success

Response Example (200 OK) 
{
  "name": "string"
}
/

POST /{subsystem}/volumes/{volume_name}/snapshots/{snapshot_name}

Create a new snapshot of volume_name under snapshot_name

SnapshotPut
undefined
volume_name

The name of the volume. Must not contain leading /. On NetApp back-ends, this may either be the name of a volume, or node_name:/junction/path.

type
string
in
path
snapshot_name

The snapshot name

type
string
in
path
subsystem

The subsystem to run the command on.

type
string
in
path
Request Example
{
  "purge_old_if_needed": "boolean"
}
201 Created

Successfully created a snapshot

409 Conflict

Too many snapshots, cannot create another. Try purge_old_if_needed=true.

Schema Definitions

Export Policy: object

name: string (at least 1 chars)
rules: string[]
Example
{
  "name": "allow_cluster_x",
  "rules": [
    "10.10.10.1/24"
  ]
}

Lock: object

host: string (at least 1 chars)
Example
{
  "host": "dbthing.cern.ch"
}

OptionalFromSnapshot:

from_snapshot: string

The snapshot name to create from/restore

from_volume: string

When cloning a volume, use this volume as basis for the snapshot to start from

Example
{
  "from_snapshot": "string",
  "from_volume": "string",
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}

PolicyRule: object

rules: string[]
Example
{
  "rules": [
    "10.10.10.1/24"
  ]
}

Snapshot: object

name: string
Example
{
  "name": "string"
}

SnapshotPut: object

purge_old_if_needed: boolean

If true, purge the oldest snapshot iff necessary to create a new one

Example
{
  "purge_old_if_needed": "boolean"
}

VolumeCreate:

aggregate_name: string (at least 1 chars)

If applicable, the aggregate to place the volume in (NetApp only). If not provided, will use the one with the most free space.

junction_path: string (at least 1 chars)
name: string (at least 1 chars)

The internal name of the volume

size_total: integer

The total size of the volume, in bytes. If creating, the size of the volume.

Example
{
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}

VolumeRead:

creation_time: string (date-time)
filer_address: string (at least 1 chars)
percentage_snapshot_reserve_used: integer
size_used: integer
state: string (at least 1 chars)
uuid: string (at least 1 chars)
Example
{
  "creation_time": "string (date-time)",
  "filer_address": "string",
  "percentage_snapshot_reserve_used": "integer",
  "size_used": "integer",
  "state": "string",
  "uuid": "string",
  "aggregate_name": "string",
  "junction_path": "string",
  "name": "volume_name",
  "size_total": "integer",
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}

VolumeWrite: object

active_policy_name: string (at least 1 chars)
autosize_enabled: boolean
autosize_increment: integer
caching_policy: string
compression_enabled: boolean
inline_compression: boolean
max_autosize: integer
percentage_snapshot_reserve: integer
Example
{
  "active_policy_name": "string",
  "autosize_enabled": "boolean",
  "autosize_increment": "integer",
  "caching_policy": "string",
  "compression_enabled": "boolean",
  "inline_compression": "boolean",
  "max_autosize": "integer",
  "percentage_snapshot_reserve": "integer"
}
Documentation by Spectacle