Shimmer

Shimmer is an application that makes it easy to pull health data from popular third-party APIs like Runkeeper and Fitbit. It converts that data into an Open mHealth compliant format, letting your application work with clean and clinically meaningful data.

We currently support the following APIs

• Fitbit
• Google Fit
• iHealth
• Misfit
• RunKeeper
• Withings

This README should have everything you need to get started. If you have any questions, feel free to open an issue, email us, post on our form, or visit our website.

Contents

• Overview
  • Shims
  • Resource server
  • Console
• Installation
  • Option 1. Download and run Docker images
  • Option 2. Build the code and run it natively or in Docker
• Registering with third-party APIs
• Postman collection
  • Setting up the Postman environment
  • Importing the Postman collection
• Authorizing access to a third-party user account
  • Authorize access using Postman
  • Authorize access programmatically
  • Authorize access from the console
• Reading data
  • Read data using Postman
  • Read data programmatically
  • Read data using the console
• Supported APIs and endpoints
• Contributing

Overview

Shimmer is made up of different components - individual shims, a resource server, and a console - which are each described below.

Shims

A shim is a library that can communicate with a specific third-party API, e.g. Fitbit. It handles the process of authenticating with the API, requesting data from it, and mapping that data into an Open mHealth compliant data format.

A shim generates data points, which are self-contained pieces of data that not only contain the health data of interest, but also include header information such as date of creation, acquisition provenance, and data source. This metadata helps describe the data and where it came from. The library is called a shim because such clean and clinically significant data is not provided natively by the third-party API.

Resource server

The resource server exposes an API to retrieve data points. The server handles API requests by delegating them to the correct shim. As more and more shims are developed and added to the resource server, it becomes capable of providing data points from more and more third-party APIs. The resource server also manages third-party access tokens on behalf of shims.

Console

The console provides a simple web interface that helps users interact with the resource server. It can trigger authentication flows, and request data using date pickers and drop downs.

Installation

There are two ways to install Shimmer.

1. You can download and run pre-built Docker images.
2. You can build all the code from source and run it natively or in Docker.

Option 1. Download and run Docker images

If you don't have Docker and Docker Compose, please set them up. (Docker for Mac, Docker for Windows).

Once you're set up, in a terminal

1. Clone this Git repository.
2. Download and start the containers using either
   • docker-compose up -d resourceserver
     • to bring up only the resource server
   • docker-compose up -d
     • to bring up the resource server and the console
   • This will download up to 0.5 GB of Docker images if you don't already have them, the bulk of which are the underlying MongoDB, nginx and OpenJDK images.
   • If you want to see logs and keep the containers in the foreground, omit the -d.
3. It can take up to a minute for the containers to start up. You can check their progress using docker-compose logs if you started with -d.
4. The console container publishes port 8083 and the resource server container publishes port 8084.
   • The console container proxies all API requests to the resource server container, so you can send API requests to port 8083 or port 8084.
5. Visit http://<shimmer-host>:8083 in a browser to open the console.

Option 2. Build the code and run it natively or in Docker

If you prefer to build the code yourself,

1. You must have a Java 8 or higher JDK installed. You can use either OpenJDK or the Oracle JDK.
2. If you're building the optional console,
   1. You need Node.js.
   2. You need Xcode Command Line Tools if you're on a Mac.
3. To run the code natively, you need a running MongoDB instance.
4. To run the code in Docker, you need Docker and Docker Compose.

If you want to build and run the code natively, in a terminal

1. Clone this Git repository.
2. Run the ./run-natively.sh script and follow the instructions.
3. When the script blocks with the message Started Application, the components are running.
   • Press Ctrl-C to stop them.
   • The script creates a WAR file which you can alternatively drop into an application server. This issue has details.
4. Visit http://<shimmer-host>:8083 in a browser to open the console.

If you want to build and run the code in Docker, in a terminal

1. Clone this Git repository.
2. Run the ./run-dockerized.sh script and follow the instructions.
   • The containers should now be running on your Docker host and expose ports 8083 and 8084.
   • It can take up to a minute for the containers to start up.
3. Visit http://<shimmer-host>:8083 in a browser to open the console.

If you can't run the Bash scripts on your system, open them and take a look at the commands they run. The important commands are marked with a "#CMD" comment.

Registering with third-party APIs

To get data from a third-party API, you need to visit the developer website of that API and register a client application. The registration information that you give to the third-party lets them show relevant information to their end users about your application, and lets them manage other operational concerns like authorization and rate limits.

You will be given a set of client credentials, usually an OAuth client ID and client secret, for each application you register. You may also need to enter a redirect URL, which is the URL a user is sent to after granting your application access to their data.

The following table contains a link to the developer portal of each API and information about redirect URL restrictions. The restrictions can be good to know about during development, but TLS and full URLs should be used during production.

API | requires TLS | allows non-FQDN hostname | allows IP addresses | allows localhost | requires URL path | example ----------------------------------------------------------------- | ------------------ | ------------------------ | ------------------- | ---------------- | ----------------- | -------- Fitbit¹ | false | true | true | true | true | http://localhost:8083/authorize/fitbit/callback Google Fit | false | false | false | true | ? | http://localhost:8083/authorize/googlefit/callback iHealth² | ? | ? | ? | ? | false | http://localhost:8083/authorize/ihealth/callback Jawbone UP | false ³ | ? | ? | ? | ? | http://localhost:8083/authorize/jawbone/callback Misfit | ? | ? | ? | ? | ? | http://localhost:8083/authorize/misfit/callback Moves | ? | ? | ? | ? | ? | http://localhost:8083/authorize/moves/callback RunKeeper | ? | ? | ? | ? | ? | http://localhost:8083/authorize/runkeeper/callba