The GDC API (or Application Programming Interface) provides users and developers
with a programmatic interface to query, download, and submit data to the GDC.
It is a fundamental layer in the architecture of the GDC and powers the user-facing apps, such as the GDC Portal
which allows users to explore, search, and download data
and the Data Transfer Tool, which allows users to submit and download data.
The API is also made publicly available, so that developers can build their own applications that interface with the GDC.
Developers have already started contributing to a growing list of these third-party apps.
While the API is targeted mostly towards developers, users can create their own ad-hoc queries to pull data from the GDC.
The API uses standard HTTP methods for these requests, such as GET, PUT, and POST.
It also uses JSON as the standard communication format in each request.
The graphic below shows a visual representation of the GDC architecture.
At the bottom are the GDC object stores, which contains harmonized and clinical and biospecimen information for projects.
The API interfaces between the underlying data in the GDC, and the internal and external applications built upon it.
Communicating with the GDC involves making calls to specific endpoints of the API URL.
Here's what the URL looks like:
Endpoints give applications and users the ability to access all the data available within the GDC Portal, including the visualization features.
The table below lists the available endpoints and a description of their functionality.
Starting at the top, users may simply get the status and version information of the API.
Search and Retrieval endpoints can be used to find information about cases, files or projects.
The download and BAM slicing endpoints can be used to download data or to download specific sections of BAM files.
Finally, the submission endpoint drives the Submission Portal and allows users to submit new data to the GDC in accordance with our data model.
The data analysis and visualization tools available in the GDC Portal also have specific API endpoints that users may use to extract data.
The table below lists these endpoints.
The first two in the list (genes and ssms) allows users to get information about specific genes or mutations.
Ssm_occurrences returns mutation information about specific instance or case.
The next four endpoints lists information about specific combinations of genes, mutations and cases.
Lastly, the survival endpoint returns the raw data used to create the survival plots seen in the data portal.
Here are some example requests to the API.
The first example returns the API status and version number.
The next two examples query the files and cases endpoints.
Each references a unique identifier, called a UUID, that identifies entities within the GDC.
These are very simple requests, but users can supply additional parameters to create more advanced queries.
Users can tack on extra parameters to perform certain functions.
For example, the filters parameter is a percent-encoded JSON that specifies the search terms of the query.
If you wanted to only get cases that correspond to breast cancer, you supply a JSON like the following:
This essentially says to return only cases or files associated with the TCGA program
with the primary site of 'breast'.
The JSON can be percent-encoded to what is seen on the right using a number of conversion tools online.
The 'fields' parameter specifies which data elements should be returned in the response.
Fields are specific properties associated with entities in the data model.
For example, if you wanted to return the ethnicity, race and gender of certain cases
you could look at our data model to find out where these fields exist, and pull them into the URL.
All the fields that exist in the data model are defined in our data dictionary or can be found at the following link:
The 'format' parameter specifies what kind of output to generate: either json, tsv, or xml.
Lastly, the size parameter specifies the number of results to be included in the response.
Using the ideas I have mentioned before, we can start to take questions and turn them into an API request.
For example, the question "How can I find the vital status and tumor stage of all breast cancer patients in the GDC"
can be made into a simple URL that can be used to bring back this information.
Firstly, you can see we have chosen to use the 'cases' endpoint because we are interested in returning information about specific patients.
The 'filters' parameter is a percent-encoded JSON that filters the results to only cases in the TCGA-BRCA project.
For the 'format' parameter, we have chosen tsv.
The 'fields' have been found using our data model.
And lastly, we've chosen a size of 10,000 to ensure enough results are returned.
The next question is, "How do we execute the query?"
There are a number of software tools available to run API requests
but the simplest is to copy and paste the URL into a browser to perform a simple GET request.
Or you can use a POST request by using the 'curl' command in a command line tool
I will demonstrate some of this right now.
Executing an API request is a simple as copying and pasting the URL into a browser of your choice.
Doing so loads the results
or downloads them to your local hard drive.
Another way to execute an API request is to use a command line tool.
The 'curl' command will create an HTTP request using the URL.
Typing 'curl' and the URL in quotes starts the request, and the results will be displayed.
Further information about the GDC API can be accessed through the GDC main portal.
Clicking 'GDC Apps' in the top corner
and choosing 'documentation' opens the GDC docs site.
The main header contains a section titled 'API' that contains all of our documentation regarding the API.
You'll find explanations and examples that will guide you, and navigate the many features of the GDC API.
U.S. Department of Health and Human Services, National Institutes of Health, National Cancer Institute
cancer.gov, 1-800-4-CANCER, produced September 2017