List the contents of a volume

This call lists the contents of a specific volume. The volume is specified as volume_id and consists of the owner and name of a volume (for example rfranklin/my-first-volume).

Request

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

Example request

GET /v2/storage/volumes/rfranklin/my-first-volume/list HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f75
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/my-first-volume/list"

Header Fields

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

Path parameters

KeyData type of valueDescription of value
volume_id
required
StringThe volume that you want to query, which consists of username of the volume owner and volume name, for example rfranklin/my-first-volume.

Query parameters

KeyData type of valueDescription of value
fieldsStringSelector specifying a subset of fields to include in the response.

Here's the list of available values for the fields parameter and their descriptions:

ValueDescription
hrefShows only the href of each returned item.
locationShows only the location (path) within the volume for each returned item.
volumeShows only the volume on which the returned item is located, in the <user-name>/<volume-name> format.
typeShows only the type of the returned item. Type is s3 for items stored on an AWS S3 bucket and gcp for items stored on a Google Cloud Storage bucket.
metadataShows only the storage-provider-generated metadata for each of the returned items.
_allShows all standard fields for each returned item, with the addition of corresponding metadata.

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-first-volume/list?limit=100",
  "limit": "100",
  "continuation_token": "Chrand0mdC1maWxlcy8yMC5pbnRlEAMPLE=",
  "truncated": true,
  "items": [
    {
      "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/rfranklin/my-first-volume/object?location=20.intervals",
      "location": "20.intervals",
      "volume": "rfranklin/my-first-volume",
      "type": "gcs",
      "metadata": {
        "bucket": "example-bucket",
        "contentType": "binary/octet-stream",
        "crc32c": "P1RVmQ==",
        "etag": "CNrand0Mvc0CEAE=",
        "generation": 1466668676135000,
        "id": "example-bucket/input-files/20.intervals/1466668676135000",
        "kind": "storage#object",
        "md5Hash": "0abcLZ/y5a/TOHXpzkfX0A==",
        "mediaLink": "https://www.googleapis.com/download/storage/v1/b/example-bucket/o/input-files%2F20.intervals?generation=1466668676135000&alt=media",
        "metageneration": 1,
        "name": "input-files/20.intervals",
        "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/o/input-files%2F20.intervals",
        "size": 9,
        "storageClass": "STANDARD",
        "timeCreated": {
          "value": 1466668676132,
          "dateOnly": false,
          "timeZoneShift": 0
        },
        "updated": {
          "value": 1466668676132,
          "dateOnly": false,
          "timeZoneShift": 0
        },
        "timeStorageClassUpdated": "2016-06-23T07:57:56.132Z"
      }
    }
  ],
  "prefixes": [],
  "links": {
    "next": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/rfranklin/my-first-volume/list?limit=2&continuation_token=Chrand0mdC1maWxlcy8yMC5pbnRlEAMPLE%3D"
  }
}

Interpreting the response body

  • href: Use the information contained in the href to make another request to obtain more details about a specific object within a volume.