Get details of a volume

This call returns details of the specified volume. The volume is referred to by its ID, which you can obtain by making the call to list all the volumes you've registered.

Path

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

Request

Example request

HTTP

GET /storage/volumes/rfranklin/output HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75

cURL

curl  -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "Content-type: application/json" -X GET "https://api.sb.biodatacatalyst.nhlbi.nih.gov/storage/volumes/rfranklin/output"

Header Fields

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

Path parameters

Key	Data type of value	Description of value
volume_id required	String	The volume that you want to query, which consists of username of the volume owner and volume name, for example rfranklin/output.

Response

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

Key	Data type of value	Description of value
active	Boolean	If a volume is deactivated, this field will be set to false
id	String	ID of this volume, containing owner/name
name	String	Name of the volume.
description	String	The description of this volume.
service	Object	This object more closely describes the mapping of the volume to the cloud service where the data is stored. See the service object section below for an explanation of its structure.
created_on	String	The date and time this volume was created.
modified_on	String	The date and time this volume was last modified.

The service object

Key	Data type of value	Description of value
type	string	The type of cloud service supported. Currently the only valid values are "s3" for Amazon Web Services and "gcs" for Google Cloud Storage.
access_mode	string	Signifies whether this volume should be used for read-write ("RW") or read-only ("RO") operations. The access mode is consulted independently of the credentials granted to the CGC when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it. default: "RW"
prefix	String	A service-specific prefix to prepend to all objects created in this volume. If the service supports folders, and this prefix includes them, the API will attempt to create any missing folders when it outputs a file. default: ""
bucket applies to type: s3 and gcs required	String	The name of the AWS S3 or GCS bucket you wish to register as a volume.
root_url default: https://s3.amazonaws.com fors3 type and https://www.googleapis.com/ for gcs	String	Cloud provider API endpoint to use when accessing this bucket. For a list of AWS-supported endpoints, see AWS Regions and Endpoints.
credentials	Object	Contains 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	String	AWS access key ID of the IAM user shared with the CGC to access this bucket.
secret_access_key applies to type: s3, if using an IAM user required	String	AWS secret access key of the IAM user shared with the Platform to access this bucket.
external_id applies to type: s3, if using an IAM role	String	Optional 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	String	The ARN (Amazon Resource Name) for the role that you want to use to connect the volume.
client_email applies to type: gcs required	String	Google Cloud Storage user email.
private_key applies to type: gcs required	String	Google Cloud Storage private key.
properties	Object	Contains properties of specific service.
sse_algorithm applies to type: s3	String	Use default AES256 server-side encryption or AWS KMS encryption when writing to this bucket. Can be: AES256 (default) aws:kms default: AES256
sse_aws_kms_key_id applies to type: s3	String	If AWS KMS encryption is used, this should be set to the required KMS key. If not set and aws:kms is set as sse_algorithm, default KMS key is used.

Example response body

JSON

{
  "active": True,
  "description": "task outputs bucket",
  "id": "rfranklin/output",
  "service": {
    "type": "s3",
    "bucket": "sbg-test-output",
    "hostname": "s3.amazonaws.com",
    "access_key": "AKIAJRC7TPMRMEXAMPLE",
    "access_mode": "RW",
    "prefix": "",
    "sse_enabled": True,
    "created_time": "2016-06-29T11:13:10+02:00",
    "updated_time": "2016-06-29T12:15:10+02:00"
  }
}