Data Submission  Assays  APIs  SDK

HuBMAP APIs

The following five APIs, available as RESTful web services, support data ingest, querying, and delivery of metadata. Data delivery is available via the Globus Transfer Service and Globus Transfer API. See the HuBMAP IDs section below for information about the ids used by the HuBMAP APIs.

Ingest API

The Ingest API supports writing data and metadata to HuBMAP. Tissue Mapping Centers (TMCs) use it to contribute data to HuBMAP and the HIVE uses it to deposit derived data resulting from the execution of pipelines.

UUID API

The UUID API supports donor and tissue sample registration, submission of data, and collection of provenance information via the Ingest UI. The Ingest UI is a web user interface used by the Tissue Mapping Centers (TMCs) when contributing raw and derived data which result from the execution of pipelines.

Search & Index API

The Search & Index API supports searching and reindexing of HuBMAP metadata and data. The /search endpoint returns sets of data entities matching specified queries for Donors, Tissue Samples, and Datasets. The /reindex endpoint is used internally to index new and changed entities, this endpoint is not accessible externally, but only from other APIs that create, update, or delete entities.

For a quick guide to query and data download access via the APIs please see the Data Query and Download example and the detailed guide to using the Search API Parameter Search feature.

Ontology/UBKG API

The Ontology API accesses an instance of a Unified Biomedical Knowledge Graph (UBKG), a neo4j knowledge graph that links infomation from a variety of biomedical vocabulary systems. The HuBMAP instance of UBKG includes HuBMAP’s application ontology that represents the HuBMAP operational model.

  • UBKG, including links to relevant GitHub repositories
  • Smart API

Entity API

The Entity API returns information about HuBMAP data entities (See Figure 1, below).

Examples of Entity endpoints are as follows:

  • /entities/types: return valid entity types
  • /entities/{identifer}: return specific entities
  • /entities/types/{type_code}: return UUIDs by entity type
  • /entities/{identifier}/provenance: return provenance data for entity

Figure 1. An example HuBMAP entity diagram including data and derived data from a pipeline.

In general, a donor and organ are required in the provenance hierarchy where tissue samples (such as blocks and samples) can be organized based on several different tissue sample types.

Human Reference Atlas (HRA) APIs

HuBMAP produces the Human Reference Atlas (HRA), see https://humanatlas.io/, which provies a comprehensive, high-resolution, three-dimensional atlas of all the cells in the healthy human body. The Human Reference Atlas provides standard terminologies and data structures for describing specimens, biological structures, and spatial positions linked to existing ontologies. In addition to user interfaces, querying of the HRA is available via APIs.

CCF API

The CCF API returns reference information about the HRA and information about experimental data registered with the HRA.

HRA via SPARQL

The HRA is published as an RDF knowledge graph and may be queried using a multitude of available libraries. It is published at several prominent biomedical ontology websites including OLS and BioPortal.

Identifiers used in HuBMAP and the APIs

HuBMAP uses three different kinds of identifiers:

HuBMAP ID

HuBMAP IDs are “human readable” identifiers that are used when displaying information about HuBMAP entities such as Donors, Tissue Samples, Datasets, and Collections.

  • Example: HBM123.ABCD.456
  • Used for identification of HuBMAP entities and referencing in HuBMAP context, e.g. in the portal UI, slides, human-human communication, etc.
  • These identifiers can be used in the APIs to query portal UI and APIs
  • There is a one-to-one mapping between HuBMAP IDs and UUIDs, with all HuBMAP IDs guaranteed to having a corresponding UUID, though not all UUIDs have a corresponding HuBMAP ID.

UUID

HuBMAP UUIDs are intended for use internally in software and data storage. They are intended for use by software and systems only and not human readable.

  • These ids are 32 digit hexadecimal numbers. Example: 0123456789abcdef0123456789abcdef
  • Used for software implementation and data storage.
  • These identifiers can be used to query the APIs and data portal.

DOI

Digital Object Identifiers (DOIs) are generated for published HuBMAP data and allow for permanent references outside of HuBMAP.

  • Example: 10.1234/HBM123.ABCD.456
  • Used for referencing outside HuBMAP context, in particular for use as references in publications.
  • Displayed as: doi:10.1234/HBM.123.ABCD.456
  • Linked to: https://doi.org/10.1234/HBM.123.ABCD.456
  • Not all HuBMAP IDs are registered as DOIs, primarily published (public) Datasets and Collections of datasets have DOIs.