ISB-CGC APIs

ISB-CGC provides a Swagger API, which interacts with the ISB-CGC Web App data, including user-generated data such as cohorts. We provide API calls pertaining to specific samples, cases, files, cohorts, and users. The syntax for all of these is available on the ISB-CGC API v4.0 UI webpage.

The ISB-CGC APIs can also be used via Python and R. We have tutorial notebooks available in our Community Notebook Repository.

Some example uses of the ISB-CGC API are:

Obtaining detailed metadata about a particular patient or sample
Creating (or retrieving a previously saved) cohort of patients and samples
Retrieving a cohort’s file manifest using the cohort ID or specific filters
Register, refresh, and unregister a specified Google Cloud Project (GCP)

Note

APIs calling user-generated data (such as your cohorts) require identity credentials.

Authorization

Some of the APIs - such as for programs, samples, and cases - can be accessed without authorization. APIs that call on information saved in a user’s account, such as the cohorts and GCP APIs, require account authorization.

In order to access the APIs that require ISB-CGC authorization, you will need to generate a credentials file on your local machine or on your VM. To load your credentials into your command line interface:

Clone the ISB-CGC-API scripts GitHub repository to your local machine.
Run the isb_auth.py script either through the command line or within Python.
If you are running the ISB-CGC APIs on a VM, upload the file generated by the above process.

ISB-CGC API v4.0 UI

The ISB-CGC API v4.0 UI displays details about the syntax for each call and also provides an interface to test requests.

To generate a subset of ISB-CGC hosted data with your desired characteristics, we have provided tools to generate cohorts of patients. In addition to the BigQuery command line, users may create and share cohorts using the ISB-CGC Web App and then access them using the Swagger UI API.

Make a Request

As mentioned before, some of the API calls will require authentication - denoted by a small lock symbol. This can be done by using the ‘Authorize’ button at the top right of the page.

For a quick demonstration of the syntax of an API call, one can test the POST/samples request. This API request has the following syntax:

{
 "barcodes": [
 <barcode 1>,
 <barcode 2>,
 ...,
 <barcode n>,
 ]
}

TCGA samples are easily selected by using the 16-character barcode, i.e. TCGA-B9-7268-01A, while patients are identified using the 12-character prefix of the sample barcode, in this case TCGA-B9-7268. Other data sets such as CCLE may use other naming conventions.

The value in the Parameters field can be edited by selecting ‘Try it out’. One can change the default sample barcodes or leave them. The request can be run by selecting ‘Execute’.

Request Response

Swagger UI submits the request and shows the curl code that was submitted. The ‘Response body’ section will display the response to the request. The expected format of the response for the above request is shown below:

{
 "data": [
 {
  "samples": [
    {
         "data_details": [
           {
             <key 1>: <value 1>,
             <key 2>: <value 2>,
             ...,
             <key n>: <value n>,
           }
         ],
         "biospecimen_data": {
           <key 1>: <value 1>,
           <key 2>: <value 2>,
           ...,
           <key n>: <value n>,
         },
         "sample_barcode": "string",
         "case_barcode": "string"
       }
     ]
   }
 ],
 "code": 0,
 "barcodes_not_found": [
   "string"
 ],
 "total_found": 0,
 "notes": "string"
}

The JSON formatted response can be downloaded by selecting the ‘Download’ button.

Warning

Any special characters in the input field will cause the request to fail. e.g. spacing in input box.
Please make sure to delete all fields not being used.
Case barcode centric requests only pull file paths specific to case entries.
Sample centric requests pull file paths specific to sample entries.
Cohorts made using the Web App will differ in sample counts from cohorts made using BigQuery tables. The Web App takes into consideration samples which correspond to pathology slide images and this information is currently not in the BigQuery tables.

For any questions or feedback on the API, please do not hesitate to contact us at feedback@isb-cgc.org.

Have feedback or corrections? Please email us at feedback@isb-cgc.org. Follow us on BlueSky and X!