tranSMART REST API

Project background• tranSMART background

– TranSMART is an open-source knowledge management and analysis platform for clinical and biological data. Started as an internal project at Johnson & Johnson in 2009, it was released as an open source project in 2012. Since then, more than 20 other pharmaceutical companies, non-profits, and academic institutions have adopted the platform for use. In 2013, the tranSMART Foundation formed as a public-private partnership to coordinate the development of the platform and promote it as the preferred data sharing and analysis platform for collaborative translational research.

• Problem Statement– The original design of TranSMART had only a single web based client interface. This has

limited ability of other analytical environments to get access to the high quality content that was captured in the underlying data mart.

• Solution– We proposed to the tranSMART community a RESTful API that would allow the retrieval of

clinical and high-dimensional data from the tranSMART data repository. To align our proposal with the needs of the broad community, we created a draft API and solicited feedback through the tranSMART Google Groups and during the tranSMART Community and Developers meetings. We also engaged the scientific community to gather use cases to test our API against. The output of this was a well vetted API proposal that could meet the needs of a diverse group of users.

tranSMART RESTful API Functionality

• The API allows a third-party application (such as R or Spotfire) to securely access tranSMART data on behalf of a user

• Study-level permissions are enforced by the API• Clinical data and high dimensional gene expression

data is currently supported• Only GET calls are supported; users cannot POST data

to tranSMART via the API• Only data from Dataset Explorer is available• The API provides a method for 3rd party application to

connect to tranSMART; however, separate plugins must developed for each application to access the API

Authentication Process• The API uses OAuth v2 for authentication. Below is the

typical authentication flow as implemented in R and Spotfire:– User opens 3rd party application (R/Spotfire) and engages the

tranSMART API package or plugin– User is prompted to enter tranSMART server URL– Application connects to tranSMART and retrieves authentication

URL for user– User follows the URL and logs in to tranSMART. User is

prompted to approve/deny the 3rd party application’s access to tranSMART

– User accepts and retrieves a token from tranSMART– User enters the token into the 3rd application– 3rd party application uses the token to access tranSMART on

behalf of the user

tranSMART RESTful API Technology Stack

• API is written in Java/Groovy• JSON for clinical data• Google’s protobuf for high dimensional data• OAuth for authentication

API Calls• All studies: /studies• Study detail: /studies/<study_id>• Subjects per study: /studies/<study_id>/subjects• Subjects detail: /studies/<study_id>/subjects/<subject_id>• Subjects per concept:

/studies/<study_id>/concepts/<concept_id>/subjects• Concepts per study: /studies/<study_id>/concepts• Concepts detail: /studies/<study_id>/concepts/<concept_id>• Observations per study: /studies/<study_id>/observations• Observations per subject:

/studies/<study_id>/subjects/<subject_id>/observations• Observations per concept:

/studies/<study_id>/concepts/<concept_id>/observations• Highdim summary: /studies/<study_id>/concepts/<concept_id>/highdim• Highdim data: /studies/<study_id>/concepts/<concept_id>/highdim?

dataType=<datatype>&projection=<projection_name>

Resources

• API code:– https://github.com/thehyve/transmart-rest-api/

• Documentation:– https://github.com/thehyve/transmart-rest-api/

blob/master/API_documentation.md