IBM Cloud API Docs

Introduction

Last updated: 2024-11-07

With the IBM® Storage Ceph® as a Service Block Storage API, you can programmatically provision and manage block storage resources within a IBM Storage Ceph as a Service deployment, including volumes, hosts, and volume to host mappings. For more information, see About IBM Storage Ceph as a Service APIs.

SDKs

SDK for Go is available for this API. The client libraries that are provided by the SDK implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries.

For more details about using IBM Storage Ceph as a Service, see docs.

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/sds-go-sdk/sdsaasv1"
)

Go get

go get -u github.com/IBM/sds-go-sdk/sdsaasv1

View on GitHub

https://github.com/IBM/sds-go-sdk

Endpoint URLs

IBM Storage Ceph as a Service Block Storage API is available in all IBM Storage Ceph as a Service deployments. To get the endpoint URL that you can use for a deployment, contact your Storage Administrator.

Authentication

The IBM Storage Ceph as a Service Block Storage API uses Identity and Access Management (IAM) to authenticate requests. To call each API method, you must be assigned a role that has access to the parent service instance. Check your access on the IBM Cloud console by navigating to Users > User > Access.

Learn about obtaining an IAM token for an authenticated user or service ID in the IAM Identity Services API.

If you first create an API key, you can use it to generate an IAM token.

To use the API, add a valid IAM token to the HTTP Authorization request header. For example, -H 'Authorization: Bearer {token}'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

  • Programmatically by constructing an IAM authenticator instance and supplying your IAM API key.
  • By defining the API key in external configuration properties, and then by using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key.

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

IAM action information

To call each method, you need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={API_KEY}'

Replace {API_KEY} with your IAM API key.

Setting client options through external configuration

Example environment variables, where {SERVICE_URL} is the endpoint URL and {API_KEY} is your IAM API key

export GLOBAL_SEARCH_URL={SERVICE_URL}
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY={API_KEY}

Example of constructing the service client

import {
    "github.com/IBM/sds-go-sdk/sdsaasv1"
}
...
authenticator := &core.IamAuthenticator{
		ApiKey: <apiKey>,
	}

sdsaasServiceOptions := &sdsaasv1.SdsaasV1Options{
		URL:           <serviceEndpoint>,
		Authenticator: authenticator,
	}

sdsaasService, err = sdsaasv1.NewSdsaasV1(sdsaasServiceOptions)
	if err != nil {
		panic(err)
	}

Auditing

Monitor API activity within your account by using the IBM Cloud Activity Tracker service. Each time that you make an API call, one or more events are generated that you can track and audit from within Activity Tracker. Specific auditing event types are listed for each individual method. For more information about how to track IBM Storage Ceph as a Service activity, see Activity tracking events for IBM Storage Ceph as a Service.

Error handling

This API uses standard HTTP response codes to indicate whether a method was completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Table 1. Error codes
HTTP Error Code Description Recovery
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all the required parameters in your request.
401 Unauthorized You are not authorized to make this request. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to perform the requested operation. You do not have valid access through IAM access policies. If this error persists, contact the account owner to check your permissions.
404 Not Found The requested resource could not be found.
405 Method Not Allowed The requested resource does not support the request method.
406 Not Acceptable The resource the client had requested is not available in a format that is allowed by the Accept header that is supplied by the client.
408 Request timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The request cannot be completed because of a conflict between the request and the current state of the resource.
500 Internal Server Error The request cannot be processed because the client encountered an unexpected condition on the server. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support.
501 Not Implemented The server either does not recognize the request method, or it lacks the ability to fulfill the request.
502 Bad Gateway The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition could also be due to an unplanned outage of a service that is needed to process the request. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support.
504 Gateway timeout The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
505 HTTP Version Not Supported The server does not support the HTTP protocol version that is used in the request.

Versioning

Requests to the IBM CephaaS Block Storage API require a major version as the first segment of the request path (/v1/).

Methods

List all Volumes

This request lists volumes in the deployment. Volumes are network-connected block storage devices that may be mapped to one or more hosts in the same deployment.

This request lists volumes in the deployment. Volumes are network-connected block storage devices that may be mapped to one or more hosts in the same deployment.

GET /volumes
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListVolumes(listVolumesOptions *ListVolumesOptions) (result *VolumeCollection, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListVolumesWithContext(ctx context.Context, listVolumesOptions *ListVolumesOptions) (result *VolumeCollection, response *core.DetailedResponse, err error)

Request

Instantiate the ListVolumesOptions struct and set the fields to provide parameter values for the ListVolumes method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Query Parameters

  • start
    string

    A server-provided token determining what resource to start the page on

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

  • limit
    integer

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 1000

    Default: 1000

    Example: 20

  • name
    string

    Filters the collection of resources with a name property matching the exact specified name

    Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

    Example: my-resource

parameter

WithContext method only

ListVolumesOptions

The ListVolumes options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/volumes?start=r134-b274-678d-4dfb-8981-c71dd9d4daa5&limit=20&name=my-resource"

Response

Response Body

VolumeCollection

A page of volumes

VolumeCollection

A page of volumes.

Status Code

  • 200

    The volumes were retrieved successfully

No Sample Response

This method does not specify any sample responses.

Create a Volume

This request creates a new volume from a volume prototype object. The prototype object is structured in the same way as a retrieved volume, and contains the information necessary to create the new volume.

This request creates a new volume from a volume prototype object. The prototype object is structured in the same way as a retrieved volume, and contains the information necessary to create the new volume.

POST /volumes
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateVolume(createVolumeOptions *CreateVolumeOptions) (result *VolumeSummary, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateVolumeWithContext(ctx context.Context, createVolumeOptions *CreateVolumeOptions) (result *VolumeSummary, response *core.DetailedResponse, err error)

Request

Instantiate the CreateVolumeOptions struct and set the fields to provide parameter values for the CreateVolume method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Request Body

Required*
VolumePrototype

Volume Template

parameter

WithContext method only

CreateVolumeOptions

The CreateVolume options.

  • curl -X POST --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   --header "Content-Type: application/json"   --data '{ "capacity": 1 }'   "${base_url}/volumes"

Response

Response Body

VolumeSummary

The volume object

VolumeSummary

The volume object.

Status Code

  • 201

    Volume creation request has been accepted

  • 400

    An invalid volume object was provided

No Sample Response

This method does not specify any sample responses.

Delete a volume

This request deletes a volume. This operation cannot be reversed. For this request to succeed, the volume must not be mapped to any hosts.

This request deletes a volume. This operation cannot be reversed. For this request to succeed, the volume must not be mapped to any hosts.

DELETE /volumes/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteVolume(deleteVolumeOptions *DeleteVolumeOptions) (response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteVolumeWithContext(ctx context.Context, deleteVolumeOptions *DeleteVolumeOptions) (response *core.DetailedResponse, err error)

Request

Instantiate the DeleteVolumeOptions struct and set the fields to provide parameter values for the DeleteVolume method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The volume identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

DeleteVolumeOptions

The DeleteVolume options.

  • curl -X DELETE --location --header "Authorization: Bearer ${iam_token}"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/volumes/${id}"

Response

Status Code

  • 204

    The volume was deleted successfully

  • 404

    Volume with specified id not found

  • 409

    Volume cannot be deleted as it is mapped to one or more hosts

No Sample Response

This method does not specify any sample responses.

Retrieve a volume

This request retrieves a single volume specified by the identifier in the URL

This request retrieves a single volume specified by the identifier in the URL.

GET /volumes/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetVolume(getVolumeOptions *GetVolumeOptions) (result *Volume, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetVolumeWithContext(ctx context.Context, getVolumeOptions *GetVolumeOptions) (result *Volume, response *core.DetailedResponse, err error)

Request

Instantiate the GetVolumeOptions struct and set the fields to provide parameter values for the GetVolume method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The volume identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

GetVolumeOptions

The GetVolume options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/volumes/${id}"

Response

Response Body

Volume

The volume object

Volume

The volume object.

Status Code

  • 200

    The volume was retrieved successfully

  • 404

    A volume with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

Update a volume

This request updates a volume with the information in a provided volume patch. The volume patch object is structured in the same way as a retrieved volume and contains only the information to be updated.

This request updates a volume with the information in a provided volume patch. The volume patch object is structured in the same way as a retrieved volume and contains only the information to be updated.

PATCH /volumes/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) UpdateVolume(updateVolumeOptions *UpdateVolumeOptions) (result *Volume, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) UpdateVolumeWithContext(ctx context.Context, updateVolumeOptions *UpdateVolumeOptions) (result *Volume, response *core.DetailedResponse, err error)

Request

Instantiate the UpdateVolumeOptions struct and set the fields to provide parameter values for the UpdateVolume method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The volume identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

Request Body

Required*
application/json-patch+jsonVolumePatch

Volume patch request body

parameter

WithContext method only

UpdateVolumeOptions

The UpdateVolume options.

  • curl -X PATCH --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   --header "Content-Type: application/json-patch+json"   --data '[]'   "${base_url}/volumes/${id}"

Response

Response Body

Volume

The volume object

Volume

The volume object.

Status Code

  • 200

    The volume update request was accepted

  • 400

    An invalid volume patch was provided

  • 404

    A volume with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

List all hosts

This request lists all hosts in the deployment. Hosts are objects representing the NVMe initiators that may be mapped to one or more volumes in the same deployment.

This request lists all hosts in the deployment. Hosts are objects representing the NVMe initiators that may be mapped to one or more volumes in the same deployment.

GET /hosts
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListHosts(listHostsOptions *ListHostsOptions) (result *HostCollection, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListHostsWithContext(ctx context.Context, listHostsOptions *ListHostsOptions) (result *HostCollection, response *core.DetailedResponse, err error)

Request

Instantiate the ListHostsOptions struct and set the fields to provide parameter values for the ListHosts method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Query Parameters

  • start
    string

    A server-provided token determining what resource to start the page on

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

  • limit
    integer

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 1000

    Default: 1000

    Example: 20

  • name
    string

    Filters the collection to resources with a name property matching the exact specified name

    Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

    Example: my-resource

parameter

WithContext method only

ListHostsOptions

The ListHosts options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts?start=r134-b274-678d-4dfb-8981-c71dd9d4daa5&limit=20&name=my-resource"

Response

Response Body

HostCollection

Collection of host objects

HostCollection

Collection of host objects.

Status Code

  • 200

    The Hosts were retrieved successfully

No Sample Response

This method does not specify any sample responses.

Create a host

This request creates a new host from a host prototype object. The prototype object contains the information necessary to provision the new host which can also be mapped to one or more volumes.

This request creates a new host from a host prototype object. The prototype object contains the information necessary to provision the new host which can also be mapped to one or more volumes.

POST /hosts
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateHost(createHostOptions *CreateHostOptions) (result *HostSummary, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateHostWithContext(ctx context.Context, createHostOptions *CreateHostOptions) (result *HostSummary, response *core.DetailedResponse, err error)

Request

Instantiate the CreateHostOptions struct and set the fields to provide parameter values for the CreateHost method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Request Body

Required*
HostPrototype

Create host request body

parameter

WithContext method only

CreateHostOptions

The CreateHost options.

  • curl -X POST --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   --header "Content-Type: application/json"   --data '{ "name": "my-host", "nqn": "nqn.2014-06.org:1234" }'   "${base_url}/hosts"

Response

Response Body

HostSummary

Host creation response

HostSummary

Host creation response.

Status Code

  • 201

    Host creation request has been accepted

  • 400

    An invalid host object was provided

No Sample Response

This method does not specify any sample responses.

Delete a Host

This request deletes a host. For this request to succeed, the host must not be mapped to any volumes.

This request deletes a host. For this request to succeed, the host must not be mapped to any volumes.

DELETE /hosts/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHost(deleteHostOptions *DeleteHostOptions) (response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHostWithContext(ctx context.Context, deleteHostOptions *DeleteHostOptions) (response *core.DetailedResponse, err error)

Request

Instantiate the DeleteHostOptions struct and set the fields to provide parameter values for the DeleteHost method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

DeleteHostOptions

The DeleteHost options.

  • curl -X DELETE --location --header "Authorization: Bearer ${iam_token}"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}"

Response

Status Code

  • 204

    The host deletion request has been accepted

  • 404

    Host with specified id not found

  • 409

    Host cannot be deleted as it is mapped to one or more Volumes

No Sample Response

This method does not specify any sample responses.

Retrieve a Host

This request retrieves a host specified by the identifier in the URL

This request retrieves a host specified by the identifier in the URL.

GET /hosts/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetHost(getHostOptions *GetHostOptions) (result *Host, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetHostWithContext(ctx context.Context, getHostOptions *GetHostOptions) (result *Host, response *core.DetailedResponse, err error)

Request

Instantiate the GetHostOptions struct and set the fields to provide parameter values for the GetHost method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

GetHostOptions

The GetHost options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}"

Response

Response Body

Host

Host Schema

Host

Host Schema.

Status Code

  • 200

    The host was retrieved successfully

  • 404

    A host with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

Update a given Host

This request updates a Host with the information in a provided host patch object. The host patch object is structured in the same way as a retrieved host and contains only the information to be updated.

This request updates a Host with the information in a provided host patch object. The host patch object is structured in the same way as a retrieved host and contains only the information to be updated.

PATCH /hosts/{id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) UpdateHost(updateHostOptions *UpdateHostOptions) (result *Host, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) UpdateHostWithContext(ctx context.Context, updateHostOptions *UpdateHostOptions) (result *Host, response *core.DetailedResponse, err error)

Request

Instantiate the UpdateHostOptions struct and set the fields to provide parameter values for the UpdateHost method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

Request Body

Required*
application/json-patch+jsonHostPatch

Host Patch body

parameter

WithContext method only

UpdateHostOptions

The UpdateHost options.

  • curl -X PATCH --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   --header "Content-Type: application/json-patch+json"   --data '[]'   "${base_url}/hosts/${id}"

Response

Response Body

Host

Host Schema

Host

Host Schema.

Status Code

  • 200

    The Host was updated successfully

  • 400

    An invalid Host patch was provided

  • 404

    A Host with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

Deletes all the volume mappings for a given host

This request deletes all volume mappings for a host

This request deletes all volume mappings for a host.

DELETE /hosts/{id}/volume_mappings
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHostMappings(deleteHostMappingsOptions *DeleteHostMappingsOptions) (response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHostMappingsWithContext(ctx context.Context, deleteHostMappingsOptions *DeleteHostMappingsOptions) (response *core.DetailedResponse, err error)

Request

Instantiate the DeleteHostMappingsOptions struct and set the fields to provide parameter values for the DeleteHostMappings method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

DeleteHostMappingsOptions

The DeleteHostMappings options.

  • curl -X DELETE --location --header "Authorization: Bearer ${iam_token}"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}/volume_mappings"

Response

Status Code

  • 204

    The deletion request was accepted

  • 404

    The specified host ID could not be found

No Sample Response

This method does not specify any sample responses.

List all volume mappings for a host

This request lists volume mappings for a host.

This request lists volume mappings for a host.

GET /hosts/{id}/volume_mappings
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListVolumeMappings(listVolumeMappingsOptions *ListVolumeMappingsOptions) (result *VolumeMappingCollection, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) ListVolumeMappingsWithContext(ctx context.Context, listVolumeMappingsOptions *ListVolumeMappingsOptions) (result *VolumeMappingCollection, response *core.DetailedResponse, err error)

Request

Instantiate the ListVolumeMappingsOptions struct and set the fields to provide parameter values for the ListVolumeMappings method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

Query Parameters

  • start
    string

    A server-provided token determining what resource to start the page on

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

  • limit
    integer

    The number of resources to return on a page

    Possible values: 1 ≤ value ≤ 1000

    Default: 1000

    Example: 20

  • name
    string

    Filters the collection of resources with a name property matching the exact specified name

    Possible values: 1 ≤ length ≤ 63, Value must match regular expression ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

    Example: my-resource

parameter

WithContext method only

ListVolumeMappingsOptions

The ListVolumeMappings options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}/volume_mappings?start=r134-b274-678d-4dfb-8981-c71dd9d4daa5&limit=20&name=my-resource"

Response

Response Body

VolumeMappingCollection

Collection of volume mappings for a host

VolumeMappingCollection

Collection of volume mappings for a host.

Status Code

  • 200

    The volume mappings were retrieved successfully

No Sample Response

This method does not specify any sample responses.

Create a Volume mapping for a host

This request creates a new volume mapping for a given host.

This request creates a new volume mapping for a given host.

POST /hosts/{id}/volume_mappings
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateVolumeMapping(createVolumeMappingOptions *CreateVolumeMappingOptions) (result *VolumeMappingReference, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) CreateVolumeMappingWithContext(ctx context.Context, createVolumeMappingOptions *CreateVolumeMappingOptions) (result *VolumeMappingReference, response *core.DetailedResponse, err error)

Request

Instantiate the CreateVolumeMappingOptions struct and set the fields to provide parameter values for the CreateVolumeMapping method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The Host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

Request Body

Required*
VolumeMappingPrototype

Volume mapping request

parameter

WithContext method only

CreateVolumeMappingOptions

The CreateVolumeMapping options.

  • curl -X POST --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   --header "Content-Type: application/json"   --data '{ "volume": { "id": "r134-b274-678d-4dfb-8981-c71dd9d4daa5" } }'   "${base_url}/hosts/${id}/volume_mappings"

Response

Response Body

VolumeMappingReference

Schema for a volume mapping to a host in pending state

VolumeMappingReference

Schema for a volume mapping to a host in pending state.

Status Code

  • 201

    Volume mapping request has been accepted. This is an asynchronous operation and its progress can be monitored using the "status".

  • 400

    An invalid volume mapping object was provided

No Sample Response

This method does not specify any sample responses.

Deletes the volume mapping

This request deletes the volume mapping

This request deletes the volume mapping.

DELETE /hosts/{id}/volume_mappings/{volume_mapping_id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHostMapping(deleteHostMappingOptions *DeleteHostMappingOptions) (response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) DeleteHostMappingWithContext(ctx context.Context, deleteHostMappingOptions *DeleteHostMappingOptions) (response *core.DetailedResponse, err error)

Request

Instantiate the DeleteHostMappingOptions struct and set the fields to provide parameter values for the DeleteHostMapping method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

  • volume_mapping_id
    Required*
    string

    The Volume mapping identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

DeleteHostMappingOptions

The DeleteHostMapping options.

  • curl -X DELETE --location --header "Authorization: Bearer ${iam_token}"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}/volume_mappings/${volume_mapping_id}"

Response

Status Code

  • 204

    The deletion request was accepted

  • 404

    The volume mapping or host with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

Retrieve a volume mapping

This request retrieves a single volume mapping specified by the identifier in the URL

This request retrieves a single volume mapping specified by the identifier in the URL.

GET /hosts/{id}/volume_mappings/{volume_mapping_id}
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetVolumeMapping(getVolumeMappingOptions *GetVolumeMappingOptions) (result *VolumeMapping, response *core.DetailedResponse, err error)
(ibmStorageCephAsAServiceBlockStorageApi *IbmStorageCephAsAServiceBlockStorageApiV1) GetVolumeMappingWithContext(ctx context.Context, getVolumeMappingOptions *GetVolumeMappingOptions) (result *VolumeMapping, response *core.DetailedResponse, err error)

Request

Instantiate the GetVolumeMappingOptions struct and set the fields to provide parameter values for the GetVolumeMapping method.

Custom Headers

  • IBM-API-Version
    Required*
    date

    The API version, in format YYYY-MM-DD. For the API behavior documented here, specify any date from 2025-02-01 to current.

    Possible values: length = 10, Value must match regular expression ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$

    Example: 2024-11-26

Path Parameters

  • id
    Required*
    string

    The host identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

  • volume_mapping_id
    Required*
    string

    The volume mapping identifier

    Possible values: 1 ≤ length ≤ 64, Value must match regular expression ^[-0-9a-z_]+$

    Example: r134-b274-678d-4dfb-8981-c71dd9d4daa5

parameter

WithContext method only

GetVolumeMappingOptions

The GetVolumeMapping options.

  • curl -X GET --location --header "Authorization: Bearer ${iam_token}"   --header "Accept: application/json"   --header "IBM-API-Version: "Mon Nov 25 18:00:00 CST 2024""   "${base_url}/hosts/${id}/volume_mappings/${volume_mapping_id}"

Response

Response Body

VolumeMapping

Volume mapping object depicting the mapping between a volume and a host

VolumeMapping

Volume mapping object depicting the mapping between a volume and a host.

Status Code

  • 200

    The volume mapping was retrieved successfully

  • 404

    A volume mapping with the specified identifier could not be found

No Sample Response

This method does not specify any sample responses.

id=curlclassName=tab-item-selected