Introduction to APIs

Estimated time: 15 minutes

Learn how an API request works, compare the resources in this module, and send a request.

Understand APIs for biomedical data

API stands for application programming interface. An API gives software a standard way to request data or an action from another system.

We will use Python to request data for the paper’s 25 gene symbols and examine the responses. Unlike results copied from a website, API requests can be repeated, checked, and shared.

Identify the parts of an API request

First, identify the parts of a request.

Term Meaning
Endpoint The web address used for a specific task
Request The message sent to the API
Parameter A value that controls the request, such as a gene or tissue ID
Response The information returned by the API
JSON A common text format used to organize returned data

A reproducible request records its endpoint, parameters, resource version, and date. Together, these details show exactly what was requested and when.

Compare the APIs used in this module

GTEx, HuBMAP, and Pharos contain different biological data. Each API answers a different question about the same 25 genes.

CFDE resource Information returned Question this resource helps answer
GTEx Portal API Median expression reported for named genes in selected heart tissues Are these genes expressed in either heart tissue?
HuBMAP APIs Indexed expression availability and summaries for up to the first 500 ventricular cardiac-myocyte records Which genes have indexed values in ventricular cardiac myocytes?
Pharos GraphQL API Protein annotations, target development level, and selected knowledge counts What is known about the encoded protein, and how developed is it as a target?

The published variant table is saved in the repository. By default, GTEx, HuBMAP, and Pharos are queried live. Dated responses support the activities during a service interruption.

The prioritization lesson also uses the ProtVar API for one missense VUS. AlphaMissense and EVE provide results from two newer missense-effect models. FoldX estimates the change in protein stability. ProtVar is an EMBL-EBI resource used after the CFDE resource activities.

Build an E-utilities request

This short syntax warm-up uses NCBI E-utilities because its endpoint and parameters are easy to inspect in one URL. Later lessons apply the same API concepts to the resources used in the analysis.

Build the URL by choosing a gene symbol, defining the parameters, and joining them to the endpoint.

Enter MYH7 or another gene symbol and choose Run Code. The final line displays the constructed NCBI request URL.

Replace the blank inside the quotation marks with a gene symbol such as MYH7 or TTN.

from urllib.parse import urlencode

# Choose a gene.
gene_symbol = "MYH7"

# Define the endpoint and search parameters.
endpoint = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi"
parameters = {
    "db": "gene",
    "term": f"{gene_symbol}[gene] AND Homo sapiens[organism]",
    "retmode": "json",
}

# Build the request URL.
request_url = f"{endpoint}?{urlencode(parameters)}"
request_url

The displayed URL sends db=gene to NCBI Gene, places the selected symbol and Homo sapiens in term, and requests JSON with retmode=json. Change gene_symbol, and the search changes with it. The endpoint and other parameters stay the same.

Send the request

Run the URL-building activity first. Then run this cell to send the request and inspect selected fields from the JSON response.

A status code of 200 confirms that NCBI received and processed the request. The match count reports how many NCBI Gene records met the search terms, while ncbi_gene_ids provides their database identifiers.

Compare API request approaches

The three resources use two common request styles.

Read a REST request

GTEx and HuBMAP provide REST-style APIs with endpoints for tasks such as retrieving expression data or finding cells. Request parameters specify the genes, tissues, or cells to return.

Read a GraphQL query

GraphQL is an API query language. A GraphQL service often uses one endpoint.

The request names the exact fields needed, while variables hold values that can change, such as a gene symbol. The response follows the shape of the query, so the client receives the fields it requested.

Pharos uses GraphQL. This query asks for a protein symbol, name, UniProt ID, target development level, and publication count:

# Give the request a name and declare the gene-symbol variable.
query TargetContext($symbol: String!) {
  # Request one target that matches the supplied symbol.
  target(q: {sym: $symbol}) {
    # Request the protein fields used in this module.
    sym
    name
    uniprot
    tdl
    publicationCount
  }
}

The fields in this query describe a protein target. The response follows the same structure and contains only the requested fields.

Check your understanding

✔

Which line defines one of the NCBI request parameters?

Correct. The db parameter tells E-utilities to search the NCBI Gene database.

This line defines the endpoint. The parameters object contains the request parameters.

This line converts the returned JSON into a Python object after the request has been sent.

✔

Which resource would you query to examine median gene expression in heart tissue?

Correct. GTEx reports median gene expression across human tissues, including the two heart tissues used in this module.

HuBMAP is used here to examine indexed expression in ventricular cardiac myocytes. GTEx provides the bulk heart-tissue measurements.

Pharos provides protein and target-development information. GTEx and HuBMAP provide expression measurements.

Key points

  • An API request specifies an endpoint and the parameters that control the response.
  • GTEx provides tissue expression, HuBMAP provides cell-type expression, and Pharos provides protein and target-development information.
  • GTEx and HuBMAP use REST-style requests; Pharos uses GraphQL.
  • ProtVar adds variant-level protein predictions for one selected missense VUS.
  • Recording identifiers, versions, and retrieval dates makes a request easier to repeat.

Other biomedical APIs

API Example use
NCBI E-utilities Search and retrieve records from NCBI resources such as Gene, PubMed, and Protein
Ensembl REST API Retrieve genes, variants, sequences, and comparative genomics data
UCSC Genome Browser API Retrieve genome sequences and selected annotation tracks

Next: Inspect the 54 published variant rows and identify the 25 gene symbols used in the API requests.

View Jupyter notebook