Block storage APIs

06/10/2021 Contributors Download PDF of this page

You can use Block Storage APIs to view and manage your block storage.

Before you create disks, you have to create block stores. When you create a disk, you have to a create host group or select an existing host group to access the disk. For more information, see Work with block storage.

Block stores

You can use Block Store APIs to retrieve and manage your block stores.

HTTP Verb Path Description Mandatory parameters/Request body

HTTP Verb	Path	Description	Mandatory parameters/Request body
`GET`	`/v2.1/blockstores`	You can retrieve the details of all your block stores. Retrieves details of the block stores, such as block store ID, IP address, region, zone, subnet ID, and tags.	`offset`: The number of items to skip before starting to collect the result set. `limit`: The numbers of items to return.
`GET`	`/v2.1/blockstores/{id}`	You can retrieve the details of a specific block store. Retrieves details of the block store, such as IP address, region, zone, subnet ID, and tags based on the entered ID.	`id`: The ID of the block store.
`POST`	`/v2.1/blockstores`	You can create a block store. Add the values in the request body to create a block store with the specified parameters, such as service protocol, subtenant ID, zone, subnet ID, and tags.	`subtenant_id`: The ID of the subtenant. `zone`: The name of the zone. `subnet_id`: The ID of the subnet.
`POST`	`/v2.1/blockstores/{id}/` `tags`	You can create or replace tags for a block store. Add the ID of the block store, and the values for the tags in the "key:value pair" format in the request body.	`id`: The ID of the block store.
`PUT`	`/v2.1/blockstores/{id}`	You can modify any block store based on its ID. Add the ID of the block store, and the values that you want to modify in the request body, such as zone, service protocol, and tags.	`id`: The ID of the block store.
`DELETE`	`/v2.1/blockstores/{id}`	You can delete any block store by its ID.	`id`: The ID of the block store.

GET

/v2.1/blockstores

You can retrieve the details of all your block stores. Retrieves details of the block stores, such as block store ID, IP address, region, zone, subnet ID, and tags.

offset: The number of items to skip before starting to collect the result set.
limit: The numbers of items to return.

GET

/v2.1/blockstores/{id}

You can retrieve the details of a specific block store. Retrieves details of the block store, such as IP address, region, zone, subnet ID, and tags based on the entered ID.

id: The ID of the block store.

POST

/v2.1/blockstores

You can create a block store. Add the values in the request body to create a block store with the specified parameters, such as service protocol, subtenant ID, zone, subnet ID, and tags.

subtenant_id: The ID of the subtenant.
zone: The name of the zone.
subnet_id: The ID of the subnet.

POST

/v2.1/blockstores/{id}/
tags

You can create or replace tags for a block store. Add the ID of the block store, and the values for the tags in the "key:value pair" format in the request body.

id: The ID of the block store.

PUT

/v2.1/blockstores/{id}

You can modify any block store based on its ID. Add the ID of the block store, and the values that you want to modify in the request body, such as zone, service protocol, and tags.

id: The ID of the block store.

DELETE

/v2.1/blockstores/{id}

You can delete any block store by its ID.

id: The ID of the block store.

Before you delete a block store, you should delete all the disks mapped to it.

Disks

You can use Disks APIs to retrieve and manage your disks.

HTTP Verb Path Description Mandatory parameters/Request body

HTTP Verb	Path	Description	Mandatory parameters/Request body
`GET`	`/v2.1/disks`	You can retrieve the details of all your disks. Retrieves details of the disks, such as block store ID, name, disk path, protocol, snapshot policy, and tags.	`offset`: The number of items to skip before starting to collect the result set. `limit`: The numbers of items to return.
`GET`	`/v2.1/disks/{id}`	You can retrieve the details of a specific disk. Retrieves details of the disk, such as block store ID, name, disk path, protocol, snapshot policy, and tags based on the entered ID.	`id`: The ID of the disk.
`POST`	`/v2.1/disks`	You can create a disk. Add the values in the request body to create a disk with the specified parameters, such as subtenant ID, zone, name, disk path, snapshot policy, backup policy, and tags.	`subtenant_id`: The ID of the subtenant. `zone`: The name of the zone. `name`: The name of the disk. `disk_path`: The path of the disk. `protocol`: The storage protocol used for block device access. `os_type`: The type of the host operating system. `hostgroup_mappings`: The host group mappings. `service_level`: The service level name applicable: Standard, Premium, Premium-Tiering, Extreme, or Extreme-Tiering. `size_gb`: The size of the disk in GBs.
`POST`	`/v2.1/disks/{id}/` `snapshot/{name}`	You can create a snapshot of a disk.	`id`: The ID of the disk. `name`: The name of the snapshot.
`POST`	`/v2.1/disks/{id}/` `tags`	You can create or replace tags for a disk. Add the ID of the disk and the values for the tags in the "key:value pair" format in the request body.	`id`: The ID of the disk.
`PUT`	`/v2.1/disks/{id}`	You can modify any disk based on its ID. Add the ID of the disk, and the values that you want to modify in the request body, such as such as name, service level, snapshot policy, backup policy, and tags.	`id`: The ID of the disk. `hostgroup_mappings`: The host group mappings.
`DELETE`	`/v2.1/disks/{id}`	You can delete any disk by its ID.	`id`: The ID of the disk.
`DELETE`	`/v2.1/disks/{id}/` `snapshot/{name}`	You can delete any snapshot of a disk by the ID of the disk and the name of the snapshot.	`id`: The ID of the disk. `name`: The name of the snapshot.

GET

/v2.1/disks

You can retrieve the details of all your disks. Retrieves details of the disks, such as block store ID, name, disk path, protocol, snapshot policy, and tags.

offset: The number of items to skip before starting to collect the result set.
limit: The numbers of items to return.

GET

/v2.1/disks/{id}

You can retrieve the details of a specific disk. Retrieves details of the disk, such as block store ID, name, disk path, protocol, snapshot policy, and tags based on the entered ID.

id: The ID of the disk.

POST

/v2.1/disks

You can create a disk. Add the values in the request body to create a disk with the specified parameters, such as subtenant ID, zone, name, disk path, snapshot policy, backup policy, and tags.

subtenant_id: The ID of the subtenant.
zone: The name of the zone.
name: The name of the disk.
disk_path: The path of the disk.
protocol: The storage protocol used for block device access.
os_type: The type of the host operating system.
hostgroup_mappings: The host group mappings.
service_level: The service level name applicable: Standard, Premium, Premium-Tiering, Extreme, or Extreme-Tiering.
size_gb: The size of the disk in GBs.

POST

/v2.1/disks/{id}/
snapshot/{name}

You can create a snapshot of a disk.

id: The ID of the disk.
name: The name of the snapshot.

POST

/v2.1/disks/{id}/
tags

You can create or replace tags for a disk. Add the ID of the disk and the values for the tags in the "key:value pair" format in the request body.

id: The ID of the disk.

PUT

/v2.1/disks/{id}

You can modify any disk based on its ID. Add the ID of the disk, and the values that you want to modify in the request body, such as such as name, service level, snapshot policy, backup policy, and tags.

id: The ID of the disk.
hostgroup_mappings: The host group mappings.

DELETE

/v2.1/disks/{id}

You can delete any disk by its ID.

id: The ID of the disk.

DELETE

/v2.1/disks/{id}/
snapshot/{name}

You can delete any snapshot of a disk by the ID of the disk and the name of the snapshot.

id: The ID of the disk.
name: The name of the snapshot.

Host groups

Access control to disks is managed with host groups. You can retrieve and manage host groups using Host Groups APIs.

HTTP Verb Path Description Mandatory parameters/Request body

HTTP Verb	Path	Description	Mandatory parameters/Request body
`GET`	`/v2.1/hostgroups`	You can retrieve the details of all your host groups. Retrieves details of the host groups, such as name, subtenant details, tenant details, zone, protocol, initiators, disks using the host group, and tags.	`offset`: The number of items to skip before starting to collect the result set. `limit`: The numbers of items to return.
`GET`	`/v2.1/hostgroups/{id}`	You can retrieve the details of a specific host group. Retrieves details of the host group, such as name, subtenant details, tenant details, zone, protocol, initiators, disks using the host groups, and tags based on the entered ID.	`id`: The ID of the host group.
`POST`	`/v2.1/hostgroups`	You can create a host group. Add the values in the request body to create a host group with the specified parameters, such as name, subtenant ID, zone, protocol, initiators, and tags.	`name`: The name of the host group. `subtenant_id`: The ID of the subtenant. `zone`: The name of the zone. `protocol`: The storage protocol used for block device access. `os_type`: The type of the host operating system.
`POST`	`/v2.1/hostgroups/{id}/` `tags`	You can create or replace tags for a host group. Add the ID of the host group and the values for the tags in the "key:value pair" format in the request body.	`id`: The ID of the host group.
`DELETE`	`/v2.1/hostgroups/{id}`	You can delete any host group by its ID.	`id`: The ID of the host group.

GET

/v2.1/hostgroups

You can retrieve the details of all your host groups. Retrieves details of the host groups, such as name, subtenant details, tenant details, zone, protocol, initiators, disks using the host group, and tags.

offset: The number of items to skip before starting to collect the result set.
limit: The numbers of items to return.

GET

/v2.1/hostgroups/{id}

You can retrieve the details of a specific host group. Retrieves details of the host group, such as name, subtenant details, tenant details, zone, protocol, initiators, disks using the host groups, and tags based on the entered ID.

id: The ID of the host group.

POST

/v2.1/hostgroups

You can create a host group. Add the values in the request body to create a host group with the specified parameters, such as name, subtenant ID, zone, protocol, initiators, and tags.

name: The name of the host group.
subtenant_id: The ID of the subtenant.
zone: The name of the zone.
protocol: The storage protocol used for block device access.
os_type: The type of the host operating system.

POST

/v2.1/hostgroups/{id}/
tags

You can create or replace tags for a host group. Add the ID of the host group and the values for the tags in the "key:value pair" format in the request body.

id: The ID of the host group.

DELETE

/v2.1/hostgroups/{id}

You can delete any host group by its ID.

id: The ID of the host group.

Initiators in a host group

You can use Host Groups APIs to retrieve and manage the initiators mapped to your host groups.

HTTP Verb Path Description Mandatory parameters/Request body

HTTP Verb	Path	Description	Mandatory parameters/Request body
`GET`	`/v2.1/hostgroups/{id}/` `initiators`	You can retrieve the details of all your initiators. Retrieves initiators and their aliases.	`id`: The ID of the host group.
`GET`	`/v2.1/hostgroups/{id}/` `initiators/{alias}`	You can retrieve the details of a specific initiator. Retrieves the initiator based on the entered ID and alias.	`id`: The ID of the host group. `alias`: The alias name of the initiator.
`POST`	`/v2.1/hostgroups/{id}/` `initiators`	You can create an initiator for a host group. Add the values for the initiator and its alias in the request body to create an initiator for the host group.	`id`: The ID of the host group. `alias`: The alias name of the initiator. `initiator`: The initiator (iSCSI Qualified Names or FC WWPNs).
`PATCH`	`/v2.1/hostgroups/{id}/` `initiators/{alias}`	You can modify an initiator. Add the new initiator in the request body.	`id`: The ID of the host group. `alias`: The alias name of the initiator. `initiator`: The initiator (iSCSI Qualified Names or FC WWPNs).`
`DELETE`	`/v2.1/hostgroups/{id}/` `initiators/{alias}`	You can delete an initiator by the ID of the host group and the alias of the initiator.	`id`: The ID of the host group. `alias`: The alias name of the initiator.

GET

/v2.1/hostgroups/{id}/
initiators

You can retrieve the details of all your initiators. Retrieves initiators and their aliases.

id: The ID of the host group.

GET

/v2.1/hostgroups/{id}/
initiators/{alias}

You can retrieve the details of a specific initiator. Retrieves the initiator based on the entered ID and alias.

id: The ID of the host group.
alias: The alias name of the initiator.

POST

/v2.1/hostgroups/{id}/
initiators

You can create an initiator for a host group. Add the values for the initiator and its alias in the request body to create an initiator for the host group.

id: The ID of the host group.
alias: The alias name of the initiator.
initiator: The initiator (iSCSI Qualified Names or FC WWPNs).

PATCH

/v2.1/hostgroups/{id}/
initiators/{alias}

You can modify an initiator. Add the new initiator in the request body.

id: The ID of the host group.
alias: The alias name of the initiator.
initiator: The initiator (iSCSI Qualified Names or FC WWPNs).`

DELETE

/v2.1/hostgroups/{id}/
initiators/{alias}

You can delete an initiator by the ID of the host group and the alias of the initiator.

id: The ID of the host group.
alias: The alias name of the initiator.

When adding initiators to a host group, the initiator should match the host group protocol. You should use IQNs for host groups with iSCSI protocol, and WWPNs for host groups with FC protocol.

Deleting an initiator from a host group affects all the disks to which the host group is mapped to.