Microsoft Health API - UWP Sample

A few days ago some updates to the Microsoft Band ecosystem were announced including Microsoft Band Web Tiles Preview and Microsoft Health Cloud APIs Preview for full details see this blog post. It’s also worth checking out the Microsoft Health developer site which has all of the details about developing for the band including getting the sensor data in real-time and also communicating to and from the band over Bluetooth.

Up until now it hasn’t been possible to consume personal data such as GPS data, sleep quality data, etc. but the Health API Preview provides a RESTful API for accessing this data. The model is that the band stores the data locally and then sync’s it with the Microsoft Health application - which is available for iOS, Android and Windows Phone (linked here https://www.microsoft.com/microsoft-health/en-gb). Your phone will sync the data from the band up to the cloud approximately every thirty minutes although you can open the Microsoft Health app and sync the data ‘manually’ whenever you like. Similar data is available via your Microsoft Health dashboard https://dashboard.microsofthealth.com/#/ after signing in with your Microsoft Account.

 

The purpose of this post is to explore the Health API Preview and show how we can create a Universal Windows Platform application that consumes them.

To get started we need to understand the auth model used which is OAuth 2.0 using the Authorization Grant flow – you can read the OAuth 2.o spec here http://tools.ietf.org/html/rfc6749 and https is used to encrypt the data in transit.

Here’s a visualisation of the auth flow (from the OAuth spec)

 

To create a UWP client you can follow the guide here Universal Windows Platform to configure your development environment. Once you are setup you can use Visual Studio to create a Blank Universal Windows project.

 

First we need to get an auth token to give us access to the APIs

The first step in that is to register an application at the Microsoft account developer center https://account.live.com/developers/applications

For full instructions on setting this up see http://developer.microsofthealth.com/Content/docs/MS%20Health%20API%20Getting%20Started.pdf

 

You can fill in some basic information about your app here although this is not mandatory.

Here’s a summary of the settings I used for the sample app

In the App Settings section you can get your Client Id and your Client Secret which you will need for the auth calls that the app will make. So the first step in that is to get an authorization code (which will be used to retrieve an OAuth access token). To do this I used the Web Authentication Broker which handles requesting user permission from the authorization server which might otherwise involve you hosting a WebView control in your app and handling the redirects to and from your app and the server. There is a useful guide to help understanding and diagnosing issues with the Web Authentication Broker here https://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh750287.aspx.

Here’s the code:

The WebAuthenticationBroker will redirect the user to login using a Microsoft account and then will prompt them to allow or deny access to the scopes requested:

If the user successfully authenticates and then allows the permissions the WebAuthenticationBroker will complete and return the authentication code to the app. Once the code is retrieved it can be used to request an access token (and refresh token):

Note. the sample app uses password vault to securely store the tokens on the client. It does the same with the Client Id and Client Secret for which it will prompt on the first run and subsequently store. The credentials can be viewed and removed using the Windows Credential Manager.

If any subsequent API calls return Unauthorised the sample will assume that the token has expired and retrieve another using the refresh token, it will then re-issue the API call with the new token.

Health API Calls

The sample app (source code on Github here https://github.com/peted70/MSHealthAPIClient) calls a selection of APIs and displays the JSON returned. I have included sample requests for:

Profile

Devices

Summaries

Activities

See the docs http://developer.microsofthealth.com/Content/docs/MS%20Health%20API%20Getting%20Started.pdf for full API details.