Registering IBM Cloud Object Storage API

Options for Cloud Object Storage Registration APIs

Table 1. Options for COS Registration APIs
Method	URI	Description
POST	`/v3/{project-id}/cos`	Registers or adds a Cloud Object Storage.
PUT	`/v3/{project-id}/cos/{cos-id}`	Updates or edits a Cloud Object Storage.
DELETE	`/v3/{project-id}/cos/{cos-id}`	Unregisters or removes a managed Cloud Object Storage.
GET	`/v3/{project-id}/cos/{cos-id}`	Shows the details of a managed COS.
GET	`/v3/{project-id}/cos`	Lists all COS that are managed.
GET	`/v3/{project-id}/cos/{cos-id}/list_images`	Shows the details of all images OVA on a COS.
GET	`v3/{project-id}/image-backups/{image-backups-id}/upload`	Uploads an image backup to a selected COS bucket.
GET	`v3/{project-id}/image-backups/{image-backups-id}/download`	Downloads an image backup from a COS bucket to the specified backup node. Image backups can be downloaded to the same or a different PowerVC management node.

Register a Cloud Object Storage

This operation adds a Cloud Object Storage in PowerVC. This API takes configuration attributes for the COS in the request body as input and registers the COS in PowerVC.

Response code

Normal Response Code: OK (201)

Request parameters

Table 2. Parameters in the request for COS registration
Name	Style	Type	Description
`name`	body	string	Display name of the COS.
`type`	body	string	Optional. Type of the COS. Default option is `ibm_cos`.
`credentials`	body	string	Includes details such as COS endpoint for the bucket, API key value in IBM Cloud service credentials, authentication endpoint (optional), and resource instance ID in IBM Cloud service credentials.
`bucket_name`	body	string	Name of the IBM Cloud bucket.

Example of registering a COS:

{
    "cos": {
        "name": "Cos-1",
        "type": "ibm_cos",
        "credentials": {
            "cos_endpoint": "https://s3.us.cloud-object-storage.appdomain.cloud",
            "cos_api_key_id": "e0n5P34667NK6IJUy##########O0-ryAkcwgMgejQkI",
            "cos_auth_endpoint": "https://iam.cloud.ibm.com/identity/token",
            "cos_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/edc47c5026c14e0b96078bf4f#####:5036b379-####-423e-####-177bc57c7da4::"
        },
        "bucket_name": "bucket-1"
    }
}

Response body

Table 3. Parameters in the response for COS registration
Name	Style	Type	Description
`COS`	body	string	Display name of the COS.
`ID`	body	string	Unique ID of the COS.

Example response when registering a COS:

{
    "cos": {
        "id": 1
    }
}

Edit a COS

This operation updates the registration information for a COS that is managed by PowerVC. This API takes the name of the COS for which you want to change the attributes in the URI and the attributes that you want to change in the body as input. The response body contains the attributes that are updated by the request.

Response codes

Normal Response Code: OK (200)

Request parameters

Table 4. Parameters in the request for updating COS details
Name	Style	Type	Description
`name`	body	string	Optional. Display name of the COS.
`credentials`	body	string	Includes details such as COS endpoint for the bucket, API key value in IBM Cloud service credentials, authentication endpoint (optional), and resource instance ID in IBM Cloud service credentials.

Example:

{
    "cos": {
        "name": "Cos-1",
        "credentials": {
        "cos_endpoint": "https://s3.us.cloud-object-storage.appdomain.cloud",
        "cos_api_key_id": "e0n5P34667NK6IJUy##########O0-ryAkcwgMgejQkI",
        "cos_auth_endpoint": "https://iam.cloud.ibm.com/identity/token",
        "cos_resource_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/edc47c5026c14e0b96078bf4f6#####:5036b379-####-423e-####-177bc57c7da4::"
        },
        
    }
}

Response body

Table 5. Parameters in the response for updating COS details
Name	Style	Type	Description
`id`	body	string	Unique ID of the COS.
`name`	body	string	Display name of the COS.
`type`	body	string	Type of the COS. Default option is `ibm_cos`.
`bucket_name`	body	string	Name of the IBM Cloud bucket.

Example response when updating a PowerVC supported COS:

{ 
     "cos" : { 
          "id" : 1, 
          "name": "Cos-1", 
          "type" : "ibm_cos", 
          "bucket_name": "bucket-1", 
    } 
}

Remove or delete a COS

This operation deletes or deregisters a COS so that it is no longer managed by PowerVC. This API takes the COS name in the URI as input and takes no request body. The API does not return any response body.

Response codes

Normal Response Code: No Content (204)

View details of a COS

This operation shows detailed information about a COS buckets that is managed by PowerVC. This API takes the COS name in the URI as input and contains no request body. The API returns the IP address and credential information of the fabric in the response body.

Response codes

Normal Response Code: OK (200)

Response body

Table 6. Parameters in the response for viewing details of a COS
Name	Style	Type	Description
`id`	body	string	Unique ID of the COS.
`name`	body	string	Display name of the COS.
`type`	body	string	Type of the COS. Default option is `ibm_cos`.
`bucket_name`	body	string	Name of the IBM Cloud bucket.

Example response when viewing the details of a COS (PowerVC supported):

{ 
     "cos" : { 
          "id" : 1, 
          "name": "Cos-1", 
          "type" : "ibm_cos", 
          "bucket_name": "bucket-1", 
    } 
}

List all COS

This operation lists the basic information about all of the COS that are managed by PowerVC. This API takes no input in the request body and returns the name and display name of each COS that is managed by PowerVC in the response body.

Response codes

Normal Response Code: OK (200)

Response body

Table 7. Parameters in the response body for viewing all the COS
Name	Style	Type	Description
`id`	body	string	Unique ID of the COS.
`name`	body	string	Display name of the COS.
`type`	body	string	Type of the COS. Default option is `ibm_cos`.
`bucket_name`	body	string	Name of the IBM Cloud bucket.

Example response when viewing list of all COS:

{ "cos" : [ 
        { 
            "id" : 1, 
            "name": "cos1", 
            "type" : "ibm_cos", 
             "bucket_name": "bucket1" 
        }, 
        { 
            "id" : 2, 
            "name": "cos2", 
            "type" : "ibm_cos", 
            "bucket_name": "bucket2"
      }   
   ] 
}

COS list images

This operation shows detailed information about all images on a COS. This API takes no input in the request body and returns the image OVA name and size in the response body.

Response codes

Normal Response Code: OK (200)

Response body

Table 8. Parameters in the response body for viewing details of all image OVAs on COS
Name	Style	Type	Description
`ova_name`	body	string	Display name of an image OVA.
`ova_size`	body	string	Size of an image OVA in GiB.

Example response when viewing list of image OVAs on a COS:

{
    "list_images": [
    {
       "ova_name": "6GB_95.ova",
        "ova_size_gb": 6
    },
    {
        "ova_name": "Demo-Export-Image-Upload_105.ova",
        "ova_size_gb": 2
    },
    {
        "ova_name": "Image_113.ova",
        "ova_size_gb": 5
    }  ]
}

COS upload image

This operation uploads an image to the specified COS bucket. This API takes COS bucket name in the request body and returns the image backup ID and the task URI in the response body.

Response codes

Normal Response Code: OK (201)

Request parameters

Table 9. Parameters in the request for uploading an image backup to COS
Name	Style	Type	Description
`cos_bucket`	body	string	Optional. Display name of the COS bucket where the image backup is being uploaded.

Example request for uploading an image backup:

{ 
  "upload": { 
        "cos_bucket": “bucket-1”
    } 
}

Response body

Table 10. Parameters in the response body for uploading an image backup to a COS
Name	Style	Type	Description
`image_backup_id`	body	string	Unique ID generated for the image backup after it is uploaded to COS bucket.
`task_uri`	body	string	Task URI is returned that can be used to monitor the progress of image backup upload operations.

Example response uploading an image to the COS:

{
    "upload": {
        "image_backup_id": 14,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=upload&task_id=6f09caf1-0468-4101-9c4d-34d0b0690s89&backup_id=23"
    }
}

COS download image

This operation downloads an image from a COS bucket. The image OVA is downloaded from COS to the backup node and an image is created on PowerVC. Images can be downloaded to the same or a different PowerVC management node. This API takes COS bucket name in the request body and returns the image backup ID and the task URI in the response body.

Response codes

Normal Response Code: OK (201)

Request parameters

Table 11. Parameters in the request for downloading an image backup from COS to the same PowerVC management node
Name	Style	Type	Description
`image_backup_id`	body	string	Image backup ID, OVA display name, or display name of the COS bucket where the image backup is being uploaded.
`backup_host`	body	string	Optional. Backup node hostname.
`display_name`	body	string	Display name of image backup.
`display_description`	body	string	Optional. Description to be added, if any.

Example request for downloading an image backup to the same PowerVC management node:

{ 
  "upload": { 
        "cos_bucket": “bucket-1”
    } 
}

Table 12. Parameters in the request for downloading an image backup from COS to a different PowerVC management node
Name	Style	Type	Description
`backup_host`	body	string	Optional. Backup node hostname.
`ova_name`	body	string	Name of the image OVA that is being downloaded.
`cos_bucket`	body	string	Name of the COS bucket.
`display_name`	body	string	Display name of the COS bucket.
`display_description`	body	string	Optional. Description to be added, if any.

Example request for downloading an image backup to a different PowerVC management node:

{ 
  "download": { 
        "backup_host": "host1" ,  
        "ova_name": "Image_113.ova", 
        "cos_bucket": "new-bucket-suman",
        "display_name": "Image_113_PVC",
        "display_description": "Downloading Image OVA from IBM COS to a different PowerVC"
    } 
}

Response body

Table 13. Parameters in the response body for downloading an image backup
Name	Style	Type	Description
`image_backup_id`	body	string	Unique ID of the image backup being downloaded.
`task_uri`	body	string	Task URI is returned that can be used to monitor the progress of image backup download operations.

Example response when downloading an image backup:

{
    "download": {
        "image_backup_id": 14,
        "task_uri": "https://9.x.x.x:9000/v3/40a58846608e4e908c43b547d4dfb58c/image-backups/get_progress?action=download&task_id=6f09caf1-0468-4101-9c4d-34d0b0690s89&backup_id=23"
    }
}