In a recent project for one of our clients, we came across a need to gather data from multiple wellness devices. We were faced with a choice between creating a custom connector for each device’s API, or using a service that gathers data in one place.
One possible solution was Human API (http://www.humanapi.co/) who stated that they provide an easy way to get data from multiple health systems and wearable devices (like Fitbit, Misfit etc.). Another one we found interesting (especially for enterprise solutions) would be Validic (https://validic.com/). We will not refer to it in this article, but it may be a focus of a separate article in the future.
In the end of this blog post, we made our conclusions regarding whether it’s cheaper to build and maintain a custom solution or to use Human API or a similar tool. For that purpose, we made a simple demo app to discover how easy (or hard) Human API integration is.
Vicert Dashboard Demo Application
The idea for our demo application is to retrieve user data from multiple wearable devices using Human API and display it using various charts. It shows the following info:
- Today’s progress – current calories burn, activity (walking, running, cycling etc.) distance and activity duration compared to the user-set goals
- Summary of calories burned, activity distance and activity duration for last 5 days
- A list of recent activities
- Calories burned for the last month
We exposed an API using a Node.js application, which connects to Human API and returns data to the client.
Authentication using HumanConnect
In order to allow Human API to collect user data, the user has to connect his/her account with Human API. This process is repeated for every service the user wants to connect.
The authentication process is done in six steps visualized in the image below (image source: http://hub.humanapi.co/docs/overview-of-human-connect):
- Angular application sends clientId (an ID received when you register your application with HumanAPI) and userId (an ID used to identify a user in our application) to user.humanapi.co service.
- HumanAPI responds with a sessionTokenObject.
- Angular application sends the sessionTokenObject to our Node.js server.
- Node.js server sends the sessionTokenObject along with the clientSecret (also received when you register your application with HumanAPI)
- HumanAPI server responds with humanId, accessToken and publicToken. This data is stored in the application database for future use.
Node.js server responds to the Angular application in order to notify that the process is finished.
Angular implementation of the Authentication process
Human API provides a widget for this purpose which you can embed into your Web or Mobile application.
First we add HumanConnect library to our application as a Bower (http://bower.io/) dependency:
We then create a factory in order to inject human connect where needed:
In the HTML template, we have a button which opens a HumanAPI connect popup
And in our Angular controller function openHumanConnect() calls the function open of the HumanConnect library, which initiates the authentication process.
Provided options object contains the following properties:
- clientUserId – an ID used to identify a user in our application
- clientId – an ID received when you register your application with HumanAPI
- publicToken – empty if connecting the user for the first time, otherwise a token received from HumanAPI during authentication (step 5).
- finish – callback function called when a response is received from HumanAPI (step 2)
Here is the implementation of the finish function:
We are posting the sessionTokenObject to our Node.js server (step 3), and we save the received public token object in the browser’s local storage (step 6).
Node.js implementation of the Authentication process
On the server side we implemented a function that handles “/human/connect” route called from the Angular application:
It calls our connect function which sends the sessionTokenObject to the Human API (step 4), and returns the received public token to the Angular application (step 6) once the request to Human API is completed.
Below is the implementation of the connect function:
As seen above, our server application sends the sessionTokenObject received from the client to Human API (step 4), and receives (step 5) the accessToken, publicToken and humanId, which are stored in our database, so that we can later access user’s data.
With everything set-up, a click on Connect Health Data button opens a full screen overlay where user can connect/disconnect an external source.
Choosing a new source sends the user to authenticate with the appropriate service and allow HumanAPI to access his/her data, through a standard OAuth or similar authentication process.
Finally, we need to fetch some data from Human API. This is pretty much straight-forward – all we need to do is to hit some of the available API endpoints providing the accessToken we have received above.
Below is an example of how to fetch a list of activities, using Node.js server:
It is also possible to provide an additional query for each request, e.g. start and end date, the number of activities being returned etc. Everything is well documented on the Human API developer hub.
Further Improvements And Optimization
In a production application, you will probably want to store user-data on your own server, and to make updates when required.
Human API provides a notification mechanism which notifies your server (via an exposed endpoint) that there is new data to be pulled from the server.
There is also a concept of batch queries which retrieves data for all your users for a specified time period. It can be executed in regular intervals to keep the data in sync.
It took us less than two days to completely set-up authentication and basic data pulling from Human API. From a developer’s perspective it was straight forward and worth the effort.
From a business perspective, you need to decide if it pays off. Take into account the estimated number of users, required connections and developer hours required for implementing and maintaining connections to required APIs, vs implementing only one API source. What makes the calculation more difficult is the fact that Human API doesn’t have publicly available pricing, so you need to contact them directly in order to get the info you need. We ran into some online gossip stating that “Human API has pricing for large enterprises as well as a mid-range plan for growing startups”, apparently for smaller startups they are open for price negotiations as well.