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). 

 Description Header  Example 
Required: Client ID  X-Client-ID  com.azumio.iphone.sleeptime
Required: OAuth token returned from /api2/token   Authorization OAuth KJK8SDF... 
 Optional: Device accesing api     X-Device-Model     X-Device-Model:iPhone
 Optional: Timezone X-Timezone X-Timezone:America/Los_Angeles
 Optional: Timezone offset X-Timezone-Offset X-Timezone-Offset:-7
 Optional: Client version X-Client-Version X-Client-Version:1.1.1

Authentication

Authentication uses OAuth 2.0 model. Every call to the API need to include the Authorization header with a token.

Browser authentication flow

  1. Register your applications client_id with Azumio. Example: org.organization.example
  2. Redirect user to https://api.azumio.com/api2/authorize?redirect_uri=http://www.example.com&client_id=org.organization.example
  3. If the user allows access he will be redirected to redirect_url with code=...
  4. 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:
  1. Retrieving list of checkins regardless of type: https://api.azumio.com/api2/checkins
  2. Retrieving list of checkins filtered by specified types: https://api.azumio.com/api2/checkins?type=steps,sleepreport
  3. 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


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.

description

parameter

example

Get data modified after specific time. Useful for synchronization. Use the modified parameter form the last entry to page data.

modifiedAfter

modifiedAfter=1349069385603

Data type. most queries need type specified.

type

type=steps

How to handle data sync if you use a local database

Important MUST follow rules:

  1. 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
  2. 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

  1. Find latest modified date in local database. If there is no entry start with 1970-01-01
  2. Call  /api2/checkins?modifiedAfter=....
  3. 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.

  • 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


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