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 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 3 rd 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 3 rd 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 3 rd party application’s access to tranSMART – User accepts and retrieves a token from tranSMART – User enters the token into the 3 rd application – 3 rd 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/ Subjects per study: /studies/ /subjects Subjects detail: /studies/ /subjects/ Subjects per concept: /studies/ /concepts/ /subjects Concepts per study: /studies/ /concepts Concepts detail: /studies/ /concepts/ Observations per study: /studies/ /observations Observations per subject: /studies/ /subjects/ /observations Observations per concept: /studies/ /concepts/ /observations Highdim summary: /studies/ /concepts/ /highdim Highdim data: /studies/ /concepts/ /highdim?dataType= &projection=

Resources API code: – Documentation: – api/blob/master/API_documentation.md