Azumio API
Contents
Basic rules
Api follow RESTfull principles. All data is transferred as a application/json.
All values should be in basic SI units (kg,second,meter...) http://en.wikipedia.org/wiki/International_System_of_Units
Dates and time should be in ISO format. (unless UNIX time is specified )
All calls should use https.
Every call to Azumio API need to have at least two headers in the header request: Client ID and OAuth token. Client ID is given at the time of registration (this is something we do and send the client ID to you).
Authentication
Authentication uses OAuth 2.0 model. Every call to the API need to include the Authorization header with a token.
Browser authentication flow
Register your applications client_id with Azumio. Example: org.organization.example
Redirect user to https://api.azumio.com/api2/authorize?redirect_uri=http://www.example.com&client_id=org.organization.example
If the user allows access he will be redirected to redirect_url with code=...
Call https://api.azumio.com/api2/token?code=...&client_id=org.organization.example&client_secret=123456&grant_type=authorization_code to get the access token
Using tokens
Pass them in Authentication header for every call either in the HTTP header or as _header parameter.
http://api.azumio.com/api2/checkins?_headers={“Authentication”:”OAuth ASFA.....SDFS"}
Accessing data
Checkins
Azumio API supports 6 different types of checkins:
Steps [type=steps]
Fitness workouts with Fitness Buddy [type=workout_log]
Sleep time [type=sleepreport]
Calories [type=calories]
Heart rate [type=heartrate]
Activity [type=activity]
Drinks [type=drink] (e.g.water, coffee,...)
Through API you can access checkin data in few different ways:
Retrieving list of checkins regardless of type: https://api.azumio.com/api2/checkins
Retrieving list of checkins filtered by specified types: https://api.azumio.com/api2/checkins?type=steps,sleepreport
Retrieving specific checkin details: https://api.azumio.com/api2/checkins/checkin_id
Checkin fragments
Some of the checkins also have fragments (details specific to checkin type such as: steps data, walking paths, location, ...).
If checkin has fragments they can be recognised in JSON property name.
Example:
{
"hasMore": true,
"checkins": [
{
"remoteid": "56446F7D-6593-...",
"#steps_profile": 123456,
"activeDuration": 2000,
"privacy_groups": [
"private"
],
"type": "steps",
...
Fragments can be accessed by specifying checkin id/fragment id and the name of the fragment (excluding # character in the name):
Steps
Example:
https://api.azumio.com/api2/checkins?type=steps
Response:
"hasMore": true,
"checkins": [
{
"remoteid": "0CE4532D-9407-421C-A0FF-E456AE247CCD",
"activeDuration": 3141,
"privacy_groups": [
"private"
],
"type": "steps",
"version": 3145,
"id": "1076547023",
"timestamp": 1391648696402,
"distance": 4271.9215087890625,
"timezone": -8,
"created": 1391587206242,
"value": 5883.272369384766,
"calories": 1708.740724224521,
"user_id": "10001",
"client_id": "your-client-id",
"end": 1391648696401,
"live": true,
"privacy": 4,
"steps": 5883.272369384766,
"modified": 1391651101440,
"walkCalories": 202.08872422452072,
"start": 1391587200000,
"basalCalories": 1506.6520000000003
]
}
Error response:
{"error": {
"errorDetail": "com.azumio.hci.AuthorizationException: User not authenticated",
"code": 401
}}
Paging data
Data cannot be paged by offset or similar methods normally used. This is due to database design.
There are several parameters that enable getting the data progressively.
How to handle data sync if you use a local database
Important MUST follow rules:
modified time is the most important field for sync and MUST ALWAYS be generated on the server. New entry in local database does not have a modified time, just a flag that the entry was
in GET /api2/checkins?modifiedAfter=.... calls use ONLY modified time that you got by calling /api2/checkins?modifiedAfter=... call. modified times returned from POST or put calls MUST NOT BE USED to sync or we’ll have a potential race condition.
This is currently the only way to ensure robustness. If you don’t follow this two rules 100% you’ll have problems.
Sync steps
Find latest modified date in local database. If there is no entry start with 1970-01-01
Call /api2/checkins?modifiedAfter=....
if hasMore is true was returned go to step 1
User profile
User profile is an expandable JSON structure.
Getting profile:
http://api.azumio.com/api2/users/me
{
"picture": "http://graph.facebook.com/123456/picture?width=128&height=128",
"id": "1",
"birthday": "2014-06-13T00:00:42",
"first_name": "John",
"name": "John Smith",
"gender": "male"
}
Webhooks
Webhooks allow you to collect information about checkin events as they happen in near real-time. In order to receive those events (new checkins and updates of existing checkins) you need to register each individual user for which you wish to receive those events. You also need to provide your callback URL so we know where to deliver them to you. Azumio Webhook will POST to that callback URL with an empty body.
Note: Webhook POST to your url has no body. You need to retrieve specific information from Azumio API when notified about the change.
Subscribe user
In order to subscribe user, the user need to be logged in and user also must allow your service to access his data.
Example: POST https://api.azumio.com/api2/subscriptions?url=http://www.example.com/callback/user/1?type=steps,sleeptime
url must be provided. It's recommended to encode this url string.
type is optional. With comma separated list of checkin types you can filter out which checkin types you wish to receive on callbacks. If type is not specified all supported checkin types will be delivered.
Calling /api2/subscriptions for a specific user multiple times, updates the callback url and type information for that user.
Get user subscriptions
Example: GET https://api.azumio.com/api2/subscriptions
Response:
{ "data": [
{
"id": "org.organization.example_34546321",
"created": 1402921264895,
"userId": "123456",
"types": [
"sleeptime",
"steps"
],
"clientId": "org.organization.example",
"url": "http://www.example.com/callback/user/1"
}
]
}
Remove user subscription
Example: DELETE https://api.azumio.com/api2/subscriptions/subscription_id