Update a volume

This call updates the details of a specific volume.

Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage.

https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/{volume_id}

Request

Example request

PATCH /v2/storage/volumes/rfranklin/output HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75
Content-Type: application/json
curl  --data '@patch-volume.json' -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-Type: application/json" -X PATCH "https://api.sb.biodatacatalyst.nhlbi.nih.gov/storage/volumes/rfranklin/output"

Header Fields

KeyDescription of value
X-SBG-Auth-Token
required
Your authentication token.
Content-type
required
application/json

Path parameters

KeyDescription of value
volume_idThe volume that you want to update.

Request body

In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.

KeyData type of valueDescription of value
descriptionStringAn optional description of this volume.
service
required
ObjectThis object should contain the information about the cloud service that this volume represents.

See the service object section below for an explanation of its structure.

The service object

KeyData type of valueDescription of value
credentialsobjectContains credentials for the underlying cloud provider.

For Amazon Web Services, these credentials depend on the type of AWS identity that is used to connect the volume, IAM role or IAM user.

AWS IAM user:
access-key-id
secret_access-key

AWS IAM role:
external_id (optional, used if an External ID is defined as required in for the role in the AWS console)
role_arn


For Google Cloud Storage, these credentials are:

client_email
private_key
access_key_id

applies to type: s3, if using an IAM user
required
stringAWS access key ID of the IAM user shared with Seven Bridges to access this bucket.
secret_access_key

applies to type: s3, if using an IAM user
required
stringAWS secret access key of the IAM user shared with Seven Bridges to access this bucket.
external_id

applies to type: s3, if using an IAM role
stringOptional information that you can use in an IAM role trust policy to designate who can assume the role. Must be provided if it is configured in your role trust policy on AWS. More info.
role_arn

applies to type: s3, if using an IAM role
required
stringThe ARN (Amazon Resource Name) for the role that you want to use to connect the volume.
client_email

applies to type: gcs
required
stringGoogle Cloud Platform user email.
private_key

applies to type: gcs
required
stringGoogle Cloud Platform private key.
endpointstringCloud provider API endpoint to use when accessing this bucket. Also includes FIPS endpoints if you need to use one.
propertiesobjectContains properties of specific service.
sse_algorithm

applies to type: s3
stringUse default AES256 server-side encryption when writing to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.)

Can be:
AES256 (default)
aws:kms
* null

default: AES256
sse_aws_kms_key_id

applies to type: s3
stringProvide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS.

Example request body

{
  "description": null,
  "service": {
    "properties": {
      "sse_algorithm": "AES256"
    }
  },
}

Response

See a list of response codes that may be contained in the body of the response.

Response body

The response object contains information about the specified volume. The information is structured using the following key-value pairs:

KeyData type of valueDescription of value
activeBooleanIf a volume is deactivated, this field will be set to false
idStringID of this volume, containing owner/name
nameStringName of the volume.
descriptionStringThe description of this volume.
serviceObjectThis object more closely describes the mapping of the volume to the cloud service where the data is stored.

See the service object section above for an explanation of its structure.
created_onStringThe date and time this volume was created.
modified_onStringThe date and time this volume was last modified.

Example response body

{
  "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/rfranklin/output",
  "id": "rfranklin/output",
  "name": "output",
  "access_mode": "RW",
  "service": {
    "type": "S3",
    "bucket": "output_bucket",
    "prefix": "outfiles",
    "endpoint": "s3.amazonaws.com",
    "credentials": {
      "access_key_id": "AKIAJRC7TPMRMEXAMPLE"
    },
    "properties": {
      "sse_algorithm": "AES256"
    }
  },
  "created_on": "2016-06-30T08:14:02Z",
  "modified_on": "2016-06-30T08:14:02Z",
  "active": true
}

👍

Note that you cannot view volumes that you have created via the visual interface. However, you can see all your volumes by making the call to list volumes.