Hypercube API server for i2b2 and TranSMART databases

Spring Boot application that serves a REST API server for i2b2 and TranSMART databases. See below for instructions on running the API server.

Configure Keycloak

The hypercube-api-server uses Keycloak as an identity provider. The following settings need to be configured before running the application.

Property	Description
keycloak.auth-server-url	Keycloak url, e.g, https://keycloak.example.com/auth
keycloak.realm	Keycloak realm.
keycloak.resource	Keycloak client id.

See application-dev.yml for example configuration.

Run

Make sure you have Java 11 and Maven installed.

From a Nexus repository

Deployment artefacts are published to the Nexus repository of The Hyve.

To fetch and run hypercube-api-server-0.0.1.jar:

# Fetch artefact from Maven
curl -f -L https://repo.thehyve.nl/service/local/repositories/releases/content/nl/thehyve/hypercube-api-server/0.0.2/hypercube-api-server-0.0.1.jar -o hypercube-api-server-0.0.1.jar && \
# Run it with:
java -jar -Dspring.config.location=classpath:config/application.yml,/path/to/config.yml target/hypercube-api-server-0.0.2.jar

From sources

# create a jar package
mvn clean package

There should now be a .jar-file in target/hypercube-api-server-0.0.1.jar.

# run the packaged application
java -jar -Dspring.config.location=classpath:config/application.yml,/path/to/config.yml target/hypercube-api-server-0.0.1.jar

There should now be an application running at http://localhost:9090/.

Usage

The application serves a REST API, documentation is available as the default page of the application: http://localhost:9090/.

Authentication

Use theAuthorize button to authenticate. A token can be obtained from Keycloak:

curl "${KEYCLOAK_SERVER_URL}/auth/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token" \
  -d "client_id=${KEYCLOAK_CLIENT_ID}" \
  -d "username=${KEYCLOAK_USERNAME}" \
  -d "password=${KEYCLOAK_PASSWORD}" \
  -d 'grant_type=password'

Use the value of the access_token field in the response as API key in the authorization dialog. N.B.: the access token typically expires quite soon.

You may consider to use the TranSMART API client for Python to interactively query the API. The API client uses offline token to obtain an access token automatically. The client converts responses to Pandas data frames.

Querying

Constraints are passed to the API server in JSON format.

To select all data in TranSMART:

{"constraint": {"type": "true"}}

To obtain counts for a constraint in example.json:

curl -v -H "Authorization: Bearer ${ACCESS_TOKEN}" -H 'Content-Type: application/json' -d '@example.json' http://localhost:9090/v2/observations/counts

Example of a variant query that could be used in the /v2/observations endpoint:

{"type": "clinical", "constraint": {"type": "and", "args": [
    {"type": "subselection", "dimension": "patient", "constraint": {"type": "and", "args": [
        {"type": "concept", "conceptCode": "Patient.gender"},
        {"type": "value", "valueType": "string", "operator": "=", "value": "male"}
    ]}}
]}}

This selects patients with value male for the Patient.gender concept (all male subjects).

Development

Run in development mode

# run the application in development mode
mvn spring-boot:run -Dspring.profiles.active=dev

Install

# install the package locally
mvn clean install

Tests

Run all tests:

mvn test

License

Copyright (c) 2019 The Hyve B.V.

The hypercube API server is licensed under the MIT License. See the file LICENSE.