Snapshot capacity usage API

Edit online

The snapshot capacity usage API gets the snapshot capacity usage for all volume snapshot for a given project or across all projects. The API is supported for the IBM FlashSystem Storwize® only.

Snapshot usage API options

Table 1. Options for snapshot usage API
Method URI Description
GET /v3/{project_id}/snapshots/usage Returns all volume snapshots for a given project across all the storage controllers.
GET /v3/{project_id}/snapshots/usage?live=true Returns a list of snapshots with current capacity from the storage backend.
GET /v3/{project_id}/snapshots/usage?all_tenants=true Returns a list of existing snapshots with details. Specify all_tenants to list the snapshots for all projects.
GET /v3/{project_id}/snapshots/usage? live=true&all_tenants=true Returns a list of snapshots with current capacity from the storage backend. Specify all_tenants to list the snapshots for all projects.
Response code
  • Normal: OK (200), Partial Content (206) - Partial results are available.
  • Failure: Bad Request (400), Internal Server Error (500)

Response body

Table 2. Parameters in the response for snapshot usage API
Name Type Description
id

String

 ID of the snapshot that is used to access the snapshot.
created_at

String

 Time when the snapshot is created.
updated_at

String

 Time when the snapshot is last updated.
name

String

 Name of the snapshot.
description

String

 Snapshot description.
volume_id

String

 ID of the volume for which the snapshot is created.
volume_type_id

String

 ID of the volume type associated with the volume for which the snapshot is created.
status

String

 Status of the snapshot. Status can be available, error, and so on.
size Integer Size with which the snapshot is created. Usually, this size is equal to the volume size.
metadata Object Snapshot metadata object that is used to store information about snapshot from the storage backend. The metadata contains these fields.
  • snapshot_wwn - Unique identifier of snapshot on storage backend.
  • snapshot_name - Name of the snapshot on storage backend.
  • used_capacity - Capacity that is being used to store data on storage backend.
  • real_capacity - Amount of physical storage that is allocated on storage backend.
  • free_capacity - Amount of free capacity that is available to store data. It is the difference of real_capacity and used_capacity.
  • capacity_units - Always in GB.
  • snapshot_usage_updated_at - Time stamp of when was the last capacity usage was updated.

The new used_capacity, free_capacity, real_capacity, capacity_units, and snapshot_usage_updated_at only parameters reflect in the output of /snapshots/usage and its associated options such as live=true and all_tenants=true. These parameters are not visible with the /snapshots or /snapshots/<snapshot-id> API outputs.
storage_nodes_snapshot_operation_status
Note: This parameter is included when the response code is 206.
 Object Snapshot operation status for each storage node.
These parameters display for every storage.
  • last_updated_at - Timestamp at which snapshot update for storage was performed at.
  • last_operation_status - This will be either “UPDATE_SUCCESSFUL” or “UPDATE_FAILED”.
  • operation_failure_reason[optional]- If the last update failed, this field will be populated.
Possible values in operation_failure_reason field:
  • LSVDISKCOPY_CALL_FAILED: Indicates lsvdiscopy call on the storage failed
  • BULK_CREATE_SNAPSHOTS_DB_OPERATION_FAILURE: Indicates bulk operation for creating records in snapshot metadata table failed
  • BULK_UPDATE_SNAPSHOTS_DB_OPERATION_FAILURE: Indicates bulk operation for updating records in snapshot metadata table failed
  • GET_SNAPSHOTS_OPERATION_FAILED: Indicated failure to fetch existing snapshots from database
  • NO_EXISTING_VDISK_COPIES: Storage backend does not have vdisk info for snapshots
  • FAILURE_IN_FORMING_SNAPSHOTS_UPDATE_AND_CREATE_INFO: Indicates the PowerVC error for forming structure internally to create/update records in metadata
  • LAST_UPDATE_CHECK_FAILED: Indicates the PowerVC was not able to check timestamp for last snapshot metadata update operation.
  • LIVE_UPDATE_METADATA_UPDATE_FAILED: Indicates the PowerVC error to update timestamp in database after creating/updating records for snapshot metadata in database.

Individual snapshot API option

Table 3. Option for individual snapshot API
Method URI Description
GET /v3/{tenant_id}/snapshots/{snapshot_id} Returns the snapshot details.
Response code
  • Normal: OK (200)
  • Failure: Bad Request (400), Internal Server Error (500)

API examples

Example 1
Table 4. Parameters in the request for example 1
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage Update and returns the snapshot usage of all snapshots. Snapshot usage data is updated at snap_usage_cache_expiration_interval interval.

Response code: 200

Example of response body.
{
    "snapshots":
        [
           {
            "id": "395593a0-65ab-4246-a20e-fea4d00965e3",
            "created_at": "2023-11-20T09:50:03.000000",
            "updated_at": "2023-11-20T09:52:08.000000",
            "name": "RRaxx_VM1_Snapshot",
            "description": "{\"vm_snapshot_flow\": true, \"inst_snap_id\": \"92a20174-a2b3-4250-94b7-ad1d1693840d\", \"inst_snap_name\": \"RRxx_VM1_Snapshot\"}",
            "volume_id": "e503404d-a976-423e-9597-fa3ee67d0bae",
            "volume_type_id": "423e-9597-fa3ee67d0bae-e503404d-a976"
            "status": "available",
            "size": 30,
            "metadata": {
                "snapshot_wwn": "6005076812810246B000000000002777",
                "snapshot_name": "snapshot-VMSnap_c8116dc5-5812--Rajni_data-15-181d1232",
                "real_capacity": "0.03562498092651367",
                "free_capacity": "0.03489255905151367",
                "used_capacity": "0.000732421875",
                "capacity_units": "GiB",
                "snapshot_capacity_updated_at": "2024-03-29T08:57:22.000000"
               }
           },
       ]
}
Example 2
Table 5. Parameters in the request for example 2
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage?all_tenants Update and returns the snapshot usage of all snapshots for all tenants. Snapshot usage data is updated at snap_usage_cache_expiration_interval interval.

Response code: 200

Example of response body.
{
    "snapshots": [
    {
        "id": "395593a0-65ab-4246-a20e-fea4d00965e3",
        "created_at": "2023-11-20T09:50:03.000000",
        "updated_at": "2023-11-20T09:52:08.000000",
        "name": "RRxx_VM1_Snapshot",
        "description": "{\"vm_snapshot_flow\": true, \"inst_snap_id\": \"92a20174-a2b3-4250-94b7-ad1d1693840d\", \"inst_snap_name\": \"RRxx_VM1_Snapshot\"}",
        "volume_id": "e503404d-a976-423e-9597-fa3ee67d0bae",
        "volume_type_id": "423e-9597-fa3ee67d0bae-e503404d-a976",
        "status": "available",
        "size": 30,
        "metadata":
        {
            "snapshot_wwn": "6005076802818DB1000000000000A892",
            "snapshot_name": "snapshot-RRxx_VM1_Snapshot-Rxx_VM1-c2e49758-00-d00965e3",
              "real_capacity": "0.03562498092651367",
                "free_capacity": "0.03489255905151367",
                "used_capacity": "0.000732421875",
                "capacity_units": "GiB",
            “snapshot_usage_updated_at”: “2023-11-23 T06:53:01.000000”
        }
    },
    {
        "id": "7c7bf4ee-7fe6-461f-8cdc-54f0afd1aba8",
        "created_at": "2023-11-07T13:05:01.000000",
        "updated_at": "2023-11-07T13:05:05.000000",
        "name": "pmax-grpsnp",
        "description": "pmax-grpsnp",
        "volume_id": "2421b2d1-9260-4010-bd03-5b293af22965",
        "volume_type_id": "423e-9597-fa3ee67d0bae-e503404d-a976",
        "status": "available",
        "size": 3,
        "metadata":
        {
            "snapshot_wwn": "6005076802818DB1000000000000A864",
            "snapshot_name": "snapshot-pmax-grpsnp-Vol-data-3-afd1aba8",
              "real_capacity": "0.03562498092651367",
                "free_capacity": "0.03489255905151367",
                "used_capacity": "0.000732421875",
                "capacity_units": "GiB",
            “snapshot_usage_updated_at”: “2023-11-23 T06:53:01.000000”
        }
    }]
}
Example 3
Table 6. Parameters in the request for example 3
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage?live=true Returns the live snapshot usage of all snapshots at snap_live_usage_ref_interval interval.

Response code: 200

Example of response body.
{
    "snapshots": [
        {
            "id": "395593a0-65ab-4246-a20e-fea4d00965e3",
            "created_at": "2023-11-20T09:50:03.000000",
            "updated_at": "2023-11-20T09:52:08.000000",
            "name": "RRxx_VM1_Snapshot",
            "description": "{\"vm_snapshot_flow\": true, \"inst_snap_id\": \"92a20174-a2b3-4250-94b7-ad1d1693840d\", \"inst_snap_name\": \"RRxx_VM1_Snapshot\"}",
            "volume_id": "e503404d-a976-423e-9597-fa3ee67d0bae",
            "status": "available",
            "size": 30,
            "metadata": {
                "snapshot_wwn": "6005076802818DB1000000000000A892",
                "snapshot_name": "snapshot-RRxx_VM1_Snapshot-Raxx_VM1-c2e49758-00-d00965e3",
                "real_capacity": "0.03562498092651367",
                "free_capacity": "0.03489255905151367",
                "used_capacity": "0.000732421875",
                "capacity_units": "GiB",
                 “snapshot_usage_updated_at”: “2023-11-23T06:53:01.000000”
            }
        }
    ]
}
Example 4
Table 7. Parameters in the request for example 4
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage?live=true When the API is partially successful, it returns the storage nodes snapshot operation status in response with the reason for not being able to partially complete the request. The storage nodes in which the operation was not successful returns the older data if snapshots still exist.

Response code: 206

Example of response body.
{  
    “storage_nodes_snapshot_operation_status”: [
            “storage-provider-host-name-1”: 
               {
                    “last_updated_at”: “2023-11-23T06:53:01.000000”,
                     “last_operation_status”: “UPDATE_SUCCESSFUL”
               },
            “storage-provider-host-name-2”: 
               {
                    “last_updated_at”: “2023-11-23T06:53:01.000100”,
                     “last_operation_status”: “UPDATE_FAILED”,
                     “operation_failure_reason”: “LSVDISKCOPY_CALL_FAILED”
 },
            “storage-provider-host-name-3”: 
               {
                    “last_updated_at”: “2023-11-23T06:53:01.000000”,
                     “last_operation_status”: “UPDATE_FAILED”,
                     “operation_failure_reason”: “LIVE_UPDATE_METADATA_UPDATED_FAILED”
 },
       ],
    "snapshots": [
        {
            "id": "395593a0-65ab-4246-a20e-fea4d00965e3",
            "created_at": "2023-11-20T09:50:03.000000",
            "updated_at": "2023-11-20T09:52:08.000000",
            "name": "RRxx_VM1_Snapshot",
            "description": "{\"vm_snapshot_flow\": true, \"inst_snap_id\": \"92a20174-a2b3-4250-94b7-ad1d1693840d\", \"inst_snap_name\": \"RRxx_VM1_Snapshot\"}",
            "volume_id": "e503404d-a976-423e-9597-fa3ee67d0bae",
            "status": "available",
            "size": 30,
            "metadata": {
                "snapshot_wwn": "6005076802818DB1000000000000A892",
                "snapshot_name": "snapshot-RRxx_VM1_Snapshot-Rxx_VM1-c2e49758-00-d00965e3",
                "real_capacity": "0.03562498092651367",
                "free_capacity": "0.03489255905151367",
                "used_capacity": "0.000732421875",
                "capacity_units": "GiB",
                 “snapshot_usage_updated_at”: “2023-11-23T06:53:01.000000”
            }
        }
    ]
}
Example 5
Table 8. Parameters in the request for example 5
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/395593a0-65ab-4246-a20e-fea4d00965e3 Returns the snapshot usage of the individual snapshot.

Response code: 200

Example of response body.
{
    "snapshot":
    {
        "id": "395593a0-65ab-4246-a20e-fea4d00965e3",
        "created_at": "2023-11-20T09:50:03.000000",
        "updated_at": "2023-11-20T09:52:08.000000",
        "name": "RRxx_VM1_Snapshot",
        "description": "{\"vm_snapshot_flow\": true, \"inst_snap_id\": \"92a20174-a2b3-4250-94b7-ad1d1693840d\", \"inst_snap_name\": \"RRxx_VM1_Snapshot\"}",
        "volume_id": "e503404d-a976-423e-9597-fa3ee67d0bae",
        "volume_type_id": "a976-423e-9597-fa3ee67d0bae-e503404d",
        "status": "available",
        "size": 30,
        "metadata":
        {
            "snapshot_wwn": "6005076802818DB1000000000000A892",
            "snapshot_name": "snapshot-RRxx_VM1_Snapshot-Rxx_VM1-c2e49758-00-d00965e3"

        }
    }
}
Example 6
Table 9. Parameters in the request for example 6
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage?live=fal This API is used when invalid values are specified in query parameters.

Response code: 400

Example of response body.
{
    "badRequest": {
        "code": 400,
        "message": "Unrecognized value 'fal', acceptable values are: '0', '1', 'f', 'false', 'n', 'no', 'off', 'on', 't', 'true', 'y', 'yes'"
    }
}
Example 7
Table 10. Parameters in the request for example 7
Method URL Description
GET https://9.xxx.xxx.xx:9000/v3/ce5b6b7a3f7344c18ada83e88c15934e/snapshots/usage?all_tenants=treu This API is used when invalid query parameters are specified.

Response code: 400

Example of response body.
{
    "badRequest": {
        "code": 400,
        "message": "Unrecognized value 'treu', acceptable values are: '0', '1', 'f', 'false', 'n', 'no', 'off', 'on', 't', 'true', 'y', 'yes'"
    }
}