Create a volume

This call creates a new volume. Volumes authorize the Platform to access and query objects on a specified cloud storage (Amazon Web Services or Google Cloud Storage) on your behalf.

Learn more about using the Volumes API for Amazon S3 and for Google Cloud Storage. These tutorials also detail how to configure your bucket.

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

Request

Example request

POST /v2/storage/volumes HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json

curl --data '@create-volume.json' -X POST -H "X-SBG-Auth-Token: ce7ae5ab85e946599298e88a3430fba0" -H "Content-Type: application/json" 'https://api.sb.biodatacatalyst.nhlbi.nih.gov/storage/volumes'

Header Fields

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

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.

Key	Data type of value	Description of value
`name` required	String	The name of the volume. It must be unique from all other volumes for this user.
`description`	String	An optional description of this volume.
`service` required	Object	This 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

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 Platform 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 for`s3` 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 Seven Bridges 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	The client email address for the Google Cloud service account to use for operations on this bucket. This can be found in the JSON containing your service account credentials.
`private_key` applies to type: `gcs` required	String	Google Cloud Platform private key.
`properties`	Object	Contains the properties of a specific service. These values set the defaults for operations performed with this volume. Individual operations can override these defaults by providing a custom `properties` object.
`sse_algorithm` applies to type: `s3`	String	S3 server-side encryption to use when exporting to this bucket. Supported values: `AES256` (SSE-S3 encryption) `aws:kms` * null (no server-side encryption). default: `AES256`
`sse_aws_kms_key_id`	String	Provide your AWS KMS ID here if you specify `aws:kms` as your `sse_algorithm`. Learn more about AWS KMS.
awscanned_acl _applies to type: `s3`	String	S3 canned ACL to apply on the object during export. Supported values: any one of S3 canned ACLs; `null` (does not apply canned ACLs). default: `null`

Example request body

{
  "name": "my_s3_volume",
  "service": {
    "type": "s3",
    "bucket": "input_files",
    "prefix": "",
    "credentials": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    },
    "properties": {
      "sse_algorithm": "AES256"
    }
  },
  "access_mode": "RO"
}

{
  "name": "my_s3_volume",
  "service": {
    "type": "s3",
    "bucket": "input_files",
    "credentials": {
      "external_id": "external-volume-id-1234",
      "role_arn": "arn:aws:iam::123456789012:role/test-volume-00"
    }
   },
  "access_mode": "RO"
}

{
  "name": "my_gcs_volume",
  "description": "New google volume",
  "service": {
    "type": "gcs",
    "bucket": "output_files",
    "prefix": "output",
    "credentials": {
      "client_email": "[email protected]",
      "private_key": "-----BEGIN RSA PRIVATE KEY-----\nrand0mIBAAKCAQEAsXj4E7svaB4szcOrAcraSbsGnNuTU1b/4llyspDa0lltZIKL\nfl5s3QoqbjUWqAZXkJexKus55g49ULD8BGKH2r4EF+XyKcpoon4uIFcbmYcmsUXM\nJ3ujgyL5DbWnQZ6GrqgFNRFVVz/PuvTZOd6KFCrjbbtCxfKoXQrmCwFC/4NlFR3v\n1kavU81w201Mied3e+pxjfiQKAJOoy5I7kfuH20xfzHXWR2YHdQGbzOUZyPgmzZ6\nH6Ry39b7bgLVbyk3++e13KrsTEf58rRzUHLzlcUDcGyf8iTO2vA2qzcbrbovwqJr\n7H4ZfFllDMYQ/ISj4cmi+sz/hR43LUK86emrXwIDAQABAoIBADBr2fvAMbINsZm+\njjTh/ObrAWXgvvSZIx3F2/Z+cUW9Ioyu1ZJ3/uncMTF6iKD1ggSwbqVQIq7zKaWP\ndGNZ4sk62PEQSx8924iiNsGaIqyj5FmvuoD3SeiorR0hd+3+a67RpwIQpaE1ht7y\nmSYh4riX7w9sbU6G44rnQ1azVG1UHvk5ieOD4OPvJopuc6D6ow1oJOnHE0k8v3HY\n1FpLdWCL6nSERqXOI5w+tllG4NMUmTZ2jhaBSEM4PIJVO+24TM3XFCcvhZ7ipPMF\nP5B8hV4hDA4Av1Ei7iuRZlJsH4sRrtHJE3/FZLgqHRRvt/7w4c1xnwirNghtTNMb\nXVoaS/ECgYEA15vL3l22mIoePlcCxIgVCAxhKm6TVQZsAE2EaeVsJKDl0AgCtn/1\nThMIPPGkO8jmjqHGgA+FhjoUQuCCdIuON00mUpmUxZlwI5+uknuK597/zAjd6W8s\n7p9apvBUDfod0hwF9Jfw+aUtZm6EAUNR1Odbb+bpXp1luwfcesHe4QcCgYEA0rg8\nZBBwh2DetU6wWh2JIejBH5SfRUqtEwo5WiEZhrEQLazcpX4w5uvESnT+xd7qx3yC\n/vyzqmy+YwP92Ql0vZApdQoyKGHVntY/o3HYxZD3x+7BKThUs747WjdSo8SwBkSr\nxEzLBgTqqcho6UXvYTTEAg11F5yNYzbvVf4vROkCgYEAh6XtTamIB9Bd1rrHcv5q\nvPWM7DVFXGj96fLbLAS7VRAlhgyEKG2417YBqNYejb6Hz5TYXhll2F0SAkFd0hU7\nFG/lfHJDt04hz0fXfTFc4yTZqnSpqQPZMQfw8LajK2gA+v/Gf2xYn7fcKGW/h0vj\nYB9u16hfirdcGZ+Ih3MR1mECgYEAnq1b1KJIirlYm8FYrVOGe4FxRF2/ngdA05Ck\nZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALJlQZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+CxZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvAL+MjZYl9Vl8pZqvAL+MZ4hpyYvs9CzX1KClL38XdaZ2ftKJB2tjzDZYl9Vl8pZqvALSi0sVSXpA=\n-----END RSA PRIVATE KEY-----"
    }
  },
  "access_mode": "RW"
}

Response

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

Example response body

{
  "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/rfranklin/my_volume",
  "id": "rfranklin/my_volume",
  "name": "my_volume",
  "access_mode": "RW",
  "service": {
    "type": "S3",
    "bucket": "output",
    "prefix": "",
    "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.

Request

Example request

Header Fields

Request body

The service object

Example request body

Response

Example response body

👍

The `service` object