Skip to content

Overview

GA4GH Data Repository Service (DRS) API is a generic interface to data repositories so data consumers, workflow systems, can access data objects in a single, standard way regardless of where they are stored and how they are managed. The primary functionality of DRS is to map a logical ID to a means for physically retrieving the data represented by the ID.

ImmPort has implemented the DRS API for accessing shared data in the following two access methods.

  • S3 Signed URL: An AWS S3 signed URL is generated for the given DRS ID. The URL expires after seven days. Files are stored in an S3 bucket in the AWS US-EAST-1 (N.Virginia) region.
  • Streaming URL: A streaming URL is generated for the given DRS ID to stream the file in bytes from the source.

The Immport DRS API endpoint requires an OAuth 2.0 bearer token to access them. Please refer below to get a ImmPort OAuth 2.0 bearer token.

Authentication

When an endpoint requires an access token, one can be obtained by sending a request to the authentication endpoint and including the ImmPort username and password.

https://www.immport.org/auth/token

Shell Command

curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD"
Results 
{
"status" : 200,
"access_token" : "Example-OiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MjMzNTE5NDMsInVzZXJfbmFtZSI6ImNhbXBqbyIsImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiIsIlJPTEVfQ1VSQVRJT05fVVNFUiIsIlJPTEVfQURNSU4iLCJST0xFX0lNTVBPUlRfREFUQV9NQU5BR0VNRU5UX0FETUlOIiwiUk9MRV9VU0VSX0FETUlOSVNUUkFUSU9OX0FETUlOIiwiUk9MRV9TSEFSSU5HX1VTRVIiLCJST0xFX0RBVEFfQlJPV1NFUl9BRE1JTiJdLCJqdGkiOiI1ZjFkMzQ3Mi03MWU5LTQ0ODUtYjQ2Zi0wM2E4MGY2Mjk4NDUiLCJjbGllbnRfaWQiOiJpbW1wb3J0LWF1dGgtdG9rZW4tY2xpZW50Iiwic2NvcGUiOlsiYnJvd3NlIiwiZG93bmxvYWQiXX0.PC9vinTYFffEMvD3UXrOq2X6DuQF_8I3HpfuzHw2EG-j8c9GufCChgRieLhmqJ8_K9ngLe_sHzvyWN6GOofUPDr5AQOGYDxurhDzWhLD58841uOQYEhbZtVF0FcO84Ybi1ld_Zgj0Rhauv2jjvZJj-vakANOndEQtsIVmMSKLcnJ93Zk8_Mxtt35yxphZOizbYMmbq8tOy40vGF4O8yHLGgJS-SEebD7shiE7DoWFW5urKvyU6szIa0sz_i1oUoBJLtVeb3pW_lpgkQ3xo4-lCBgK2SkEvdq5g-So5cUNKzW619Tcznjs68z88droOX3gqu3oHxO4Z5Do824_2lzeA"
}

The token returned is a JWT token. JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

The token must be used to initiate a API request that requires authentication within 3600 seconds. After 3600 seconds the token will be invalid and the user will need to get a new token.

FHIR API

Once the studies of interest are found in ImmPort FHIR. Use the FHIR API endpoint below to get the Related Artifacts for the study. Currently in FHIR, ImmPort is using the supports type in the RelatedArtifact section of the response to indicate it is a study file (This section has a DRS URL to the study file).

#!/bin/bash
export token=`curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"access_token"' | sed -e 's/^.*"access_token":"//;s/".*$//'`
echo $token

curl -k -H "Authorization: Bearer $token" -X GET "https://fhir.immport.org/fhir/ResearchStudy/SDY1"

FHIR EndPoint Response: 

    Partial output from the above API endpoint is shown below. 

    ......
    "relatedArtifact": [ 
    {
    "type": "citation",
    "label": "Clinicaltrials.gov",
    "display": "Clinicaltrials.gov",
    "document": {
      "url": "http://clinicaltrials.gov/ct2/show/NCT00078195"
    }
    }, {
    "type": "citation",
    "label": "ImmuneTolerance.org",
    "display": "ImmuneTolerance.org",
    "document": {
      "url": "http://www.immunetolerance.org/studies/efficacy-and-safety-evaluation-allergen-immunotherapy-co-administered-with-omalizumab-anti-i"
    }
    }, {
    "type": "documents",
    "label": "Study Data",
    "display": "Site-based Pollen data",
    "document": {
      "contentType": "text/plain",
      "url": "https://www.immport.org/browser/?path=SDY1/StudyFiles",
      "size": 38327,
      "hash": "318c6e107b98a406fed3c2e906eb6996",
      "title": "PLN_2013-11-25_09-14-44.txt"
    }
    }, {
    "type": "supports",
    "label": "Study Data",
    "display": "Site-based Pollen data",
    "document": {
      "contentType": "text/plain",
      "url": "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6",
      "size": 38327,
      "hash": "318c6e107b98a406fed3c2e906eb6996",
      "title": "PLN_2013-11-25_09-14-44.txt"
    }
    }, {
    "type": "documents",
    "label": "Study Data",
    "display": "Apoptosis Data",
    "document": {
      "contentType": "text/plain",
      "url": "https://www.immport.org/browser/?path=SDY1/StudyFiles",
      "size": 216578,
      "hash": "f463abd05a9ea47ae31d7b5cb907bffb",
      "title": "Apoptosis_2013-01-11_14-29-50.txt"
    }
    },{
    "type": "supports",
    "label": "Study Data",
    "display": "Apoptosis Data",
    "document": {
      "contentType": "text/plain",
      "url": "https://drs.immport.org/ga4gh/drs/v1/objects/299e9d6e-a097-4658-b8cc-6023486979c7",
      "size": 216578,
      "hash": "f463abd05a9ea47ae31d7b5cb907bffb",
      "title": "Apoptosis_2013-01-11_14-29-50.txt"
    }
    }, {
    "type": "documents",
    "label": "Data Dictionary",
    "display": "Study variable specifications",
    "document": {
      "contentType": "application/msword",
      "url": "https://www.immport.org/browser/?path=SDY1/StudyFiles",
      "size": 691712,
      "hash": "1d69cc27340cac9c1439448afc22a294",
      "title": "20050413_Final_Analysis_Created_Variable_Specifications.doc"
    }
    }, {
    "type": "supports",
    "label": "Data Dictionary",
    "display": "Study variable specifications",
    "document": {
      "contentType": "application/msword",
      "url": "https://drs.immport.org/ga4gh/drs/v1/objects/7c99b0e4-7c12-4dbb-bbfe-3854db25269c",
      "size": 691712,
      "hash": "1d69cc27340cac9c1439448afc22a294",
      "title": "20050413_Final_Analysis_Created_Variable_Specifications.doc"
    }
    },......

Sample API call to a DRS API endpoint

In the following example, an authentication token is saved as an environment variable (token) and passed to the HTTP header in the curl command to retrieve access endpoint UUIDs for the DRS URL that was retrieved in the previous example.

The first line is a POST to the authentication URL https://www.immport.org/auth/token with the username and password to get an authentication token. The fgrep command is used search the response for a token and then assign the value of the token to an environment variable named "token".

The second line is a GET on the DRS URL https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6 that is got from the FHIR endpoint response as shown above. The supports type of the related artifact has the drs url for each of the study file associated with the study,

The authentication token ("token") is passed in the HTTP header as shown.

The response will return two access UUIDs for the resource represented by the UUID ddd17e17-e2d5-418a-8e6b-42487726b9a6. This UUID represents the file PLN_2013-11-25_09-14-44.txt that contains Pollen data.

The above shell script or any code starting with #!/bin/bash can be copied to a .sh file (e.g. SDY1_DRS.sh )and executed at the command prompt of a terminal and the output can be directed to a file. (Please replace the REPLACE_WITH_USERNAME with your username and REPLACE_WITH_PASSWORD with your password.)

#!/bin/bash

export token=`curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"access_token"' | sed -e 's/^.*"access_token":"//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6"

Results 

{
"id" : "ddd17e17-e2d5-418a-8e6b-42487726b9a6",
"description" : "SDY1-PLN_2013-11-25_09-14-44.txt",
"created_time" : "2024-04-30T16:17:20Z",
"mime_type" : "text/plain",
"name" : "PLN_2013-11-25_09-14-44.txt",
"size" : 38327,
"updated_time" : "2024-04-30T16:17:20Z",
"checksums" : [ {
    "checksum" : "318c6e107b98a406fed3c2e906eb6996",
    "type" : "md5"
} ],
"self_uri" : "drs://drs.immport.org:/ddd17e17-e2d5-418a-8e6b-42487726b9a6",
"access_methods" : [ {
    "access_id" : "83097414-06f6-46d7-a7dc-ac6e5609ce2e",
    "type" : "https"
}, {
    "access_id" : "5e10e701-c48b-44da-9450-617d8b1f3a82",
    "type" : "s3",
    "region" : "US East (N. Virginia) us-east-1"
} ]
}

The above output returns two access method UUID:

  • Access Id for Streaming URL Endpoint (https) - 83097414-06f6-46d7-a7dc-ac6e5609ce2e
  • Access Id for S3 Signed URL Endpoint (s3) - 5e10e701-c48b-44da-9450-617d8b1f3a82

To get the Streaming URL Endpoint, use the streamimg access UUID as shown below:

#!/bin/bash

export token=`curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"access_token"' | sed -e 's/^.*"access_token":"//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6/access/83097414-06f6-46d7-a7dc-ac6e5609ce2e"

Results 

{
    "url" : "https://drs.immport.org/ga4gh/drs/v1/stream/ddd17e17-e2d5-418a-8e6b-42487726b9a6/83097414-06f6-46d7-a7dc-ac6e5609ce2e"
}

The above streaming endpoint can stream the file to the specified destination

To get the S3 URL Endpoint, use the s3 access UUID as shown below:

#!/bin/bash

export token=`curl -X POST https://www.immport.org/auth/token -d username="REPLACE_WITH_USERNAME" -d password="REPLACE_WITH_PASSWORD" 2>&1  | fgrep '"access_token"' | sed -e 's/^.*"access_token":"//;s/".*$//'`

curl -k -H "Authorization: bearer $token" "https://drs.immport.org/ga4gh/drs/v1/objects/ddd17e17-e2d5-418a-8e6b-42487726b9a6/access/5e10e701-c48b-44da-9450-617d8b1f3a82"

Results

{
  "url" : "https://immport-strides-prod-shared-data.s3.amazonaws.com/SDY1/StudyFiles/PLN_2013-11-25_09-14-44.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240504T140525Z&X-Amz-SignedHeaders=host&X-Amz-Expires=26400&X-Amz-Credential=AKIAQ3E4VVSLOIIOEVAS%2F20240504%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=6ab32cba03769be778291e888a68f0755297a7ef264594269742f882e426da4d"
}

The above S3 endpoint can download the file to the specified destination

Tutorial

Click the link below to access the ImmPort FHIR-DRS API tutorial. This tutorial shows how to use FHIR endpoint to get study files related to a study of interest and then use the DRS API to stream/download data to a specified destination

ImmPort FHIR-DRS API tutorial

The above URL requires a ImmPort Login to access it.