Start an export job

🚧

Advance Access

This request contains an Advance Access parameter, copy_only. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.

As we haven't fully integrated it in our main API branch, there might be slight changes to the paths or parameter names. If you are a software developer, think "beta access" but with fewer expected bugs.

We are confident, however, that the feature is ready for use by our customers and partners who are willing to slightly modify their scripts at a later date.

This call lets you queue a job to export a file from a project on the Platform into a volume. The file selected for export must not be a public file or an alias. Aliases are objects stored in your cloud storage bucket which have been made available on the Platform.

The volume you are exporting to must be configured for read-write access. To do this, set the access_mode parameter to RW when creating or modifying a volume.

Essentially, the call writes to your cloud storage bucket on Amazon Web Services or Google Cloud Storage via the volume. If this call is successful, the original project file will become an alias to the newly exported object on the volume. The source file will be deleted from the Platform and, if no more copies of this file exist, it will no longer count towards your total storage price on the Platform.

In summary, once you export a file from the Platform to a volume, it is no longer part of the storage on the Platform and cannot be exported again.

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

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

Request

Header Fields

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

Query parameters

KeyData type of valueDescription of value
overwriteBooleanIf true and a file exists in the given location on the volume (respecting volume prefix if given), the API will attempt to delete the existing file on the volume before exporting.

default: false

Query parameters - Advance Access

The following parameter is Advance Access. This means that, while it is fully operational, it is subject to change. Learn more about this feature below.

KeyData type of valueDescription
copy_onlyBooleanIf true, file will be copied to a volume but source file will remain on the Platform.

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
source
required
ObjectThis object should describe the source from which the file should be exported.
file
required
StringThe ID of the file for export.
destination
required
ObjectThis object should describe the destination to which the file will be exported.
volume
required
StringThe ID of the volume to which the file will be exported.
location
required
StringVolume-specific location to which the file will be exported. This location should be recognizable to the underlying cloud service as a valid key or path to a new file.

Please note that if this volume has been configured with a prefix parameter, the value of prefix will be prepended to location before attempting to create the file on the volume.
propertiesObjectService-specific properties of the export.

These values override the defaults from the volume.
sse_algorithmStringS3 server-side encryption to use when exporting to this bucket.

Supported values:
AES256 (SSE-S3 encryption);
null (no server-side encryption).

default: AES256
sse_aws_kms_key_id

applies to type: s3
StringIf 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.
aws_canned_aclStringS3 canned ACL to apply on the object on during export.

Supported values:
any one of S3 canned ACLs;
null (do not apply canned ACLs).

default: null.

Example Request (normal)

POST /v2/storage/exports HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json
{
  "destination":{ 
    "volume":"rfranklin/output",
    "location":"output.vcf"
 },
  "source":{
      "file":"567890abc9b0307bc0414164"
  },
  "overwrite":false
}

Example request (Advance Access - copy file only)

POST /v2/storage/exports?copy_only=true HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
{
  "destination":{ 
    "volume":"rfranklin/output",
    "location":"output.vcf"
 },
  "source":{
      "file":"567890abc9b0307bc0414164"
  },
  "overwrite":false
}

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 status of the export job. The information is structured using the following key-value pairs:

KeyData type of valueDescription of value
idStringID of this export job
stateStringThe state of this export job. Possible values are:
PENDING: the export is queued
RUNNING: the export is running
COMPLETED: the export has completed successfully
FAILED: the export has failed
sourceObjectExport source, as passed when this job was started by the call to Start an export job.
destinationObjectExport destination, as passed when this job was started by the call to Start an export job.
resultObjectFile object that was exported.
errorObjectIn case of error in the export job, standard API error is returned here.

Example response body

{
  "href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/exports/erand0md6gMeuLlhWTNVj192RsnOMgdB",
  "id": "erand0md6gMeuLlhWTNVj192RsnOMgdB",
  "state": "PENDING",
  "source": {
    "file": "567890abc9b0307bc0414164"
  },
  "destination": {
    "volume": "rfranklin/output",
    "location": "output.vcf"
  },
  "started_on": "2016-06-15T19:17:39Z",
  "properties": {
    "sse_algorithm": "AES256"
  },
  "overwrite": false
}