BodyTrack server APIs

Owned by Anne Wright
Last updated: Dec 16, 2013
6 min read

Table of Contents

Overview

The following are APIs implemented within the Fluxtream server.  The code implementing the back end support for these calls are in BodyTrackController.java.  Changes in that code may be more recent than this document.  When in doubt, please contact us at info@fluxtream.org.

Authentication and guest ID

You can either use basic auth or session-based management for authentication using the user's username and password.  The examples here are for using basic auth.  Managing cookies is outside the scope of this document.

Note that the web site piece of Fluxtream has recently been modified to accept email addresses in lieu of usernames in deference to cultural changes in what people expect.  However, these APIs have not been modified or tested to support use of email addresses.  

If you only know your email address and not your username, you can log in and check the account settings dialog for your username.

Get the ID for the guest

/api/guest

Returns json reflecting the account info for the logged in user.  The most important field to be aware of is the id field.  This is the numeric user ID corresponding with the authentication credentials provided.  You'll need to be able to get this ID to use with other API calls.


Example, good credentials:

  curl -u test:testtest http://fluxtream.org/api/guest
    {"username":"test","firstname":"test","lastname":"test","email":"foo@bar.com","roles":"[ROLE_USER]","id":1}

If user is not logged in, returns status code 401

Data access

Data sources, devices and channels

A data source can either represent a physical device, like a cell phone or a chest strap, or any other source of data, such as from an observation capture app.  Each data source in the system for a given user has a unique device name and may contain one or more channels.  For historical reasons, the name of the data source to upload to is generally referred to as dev_nickname.  

A data channel within a device also has a name, but that name must only be unique within the device.  

Source and channel names must include only alphanumeric characters (A-Z, a-z, 0-9) plus underscores.  If the names contain other characters they will be converted by the server to underscores.  

Formatting of time

All time fields is represented as double-precision floating point time in seconds since Jan 1, 1970 in UTC, not counting leap second (standard UNIX-style time).  Decimal seconds are allowed.  Times before 1/1/70 are representable by negative numbers.

Fetch tile

/api/bodytrack/tiles/UID/DeviceNickname.ChannelName/Level.Offset.json

Note that negative levels are valid;  the system is designed to work with double-precision floating point timestamps, with effective resolution of 1 ns for contemporary times

Notes:
- Negative offsets are valid and represent times before Jan 1, 1970
- A 64-bit signed integer is sufficient for storing offset, while a 32-bit integer is not.


Returns
{
   "fields":["time","mean","stddev","count"],
   "data":[
               [1352729398.800067,0.966,1.485415458679199,15],
               [1352729423.768154,0.6116538461538461,0.04332740977406502,52],
                ...
               [1352743298.36375,0.51925,0.1960801780223846,8],
               [1352744129.181875,-1E+308,0,0]
             ],
   "level":5,
   "offset":82564,
   "sample_width":32,
   "type":"value"
}

Tags

/api/bodytrack/users/UID/tags

Returns a JSON object containing a tags field whose value is array of tag strings. 

  curl -u test:testtest http://fluxtream.org/api/bodytrack/users/1/tags
    {"tags":[energy","fruit","garden","headache"]}

 

Data upload

Storing data

/api/bodytrack/upload?dev_nickname=<name>&channel_names=<channel_names>&data=<data>

POSTs data for a given source to a given user's account.  Uses basic auth for both authentication to determine which user the data is being uploaded to.  Required parameters are:

  • dev_nickname Name of the data source to upload the data to (alphanumeric + underscores, unique to a given user)
  • channel_names  JSON encoded array of channel names.   
    Example: ["temperature", "humidity"]

  • data JSON encoded array of arrays of time samples, in the same order as channel names.  Time is always the first column (and not mentioned in the channel names above).  
    Example: [[1234152345.2, 45.9, 95.02], [1234152355.3, 45.8, 95.10]]


Example: 

  curl -i -u test:testtest http://fluxtream.org/api/bodytrack/upload -d dev_nickname=test -d channel_names='["a","b"]' -d data='[[1332754616,1,10], [1332754617,-1,20]]'

Returns:

{"max_datetime":null,"min_time":1332754616,"failed_records":0,"channel_specs":{"a":{"max_value":1,"min_value":-1,"min_time":1332754616,"channel_bounds":{"max_value":1,"min_value":-1,"min_time":1332754616,"max_time":1332754617},"imported_bounds":{"max_value":1,"min_value":-1,"min_time":1332754616,"max_time":1332754617},"max_time":1332754617},"b":{"max_value":20,"min_value":10,"min_time":1332754616,"channel_bounds":{"max_value":20,"min_value":10,"min_time":1332754616,"max_time":1332754617},"imported_bounds":{"max_value":20,"min_value":10,"min_time":1332754616,"max_time":1332754617},"max_time":1332754617}},"logrec_id":85284,"successful_records":1,"min_datetime":null,"max_time":1332754617}

Storing photos

/api/bodytrack/photoUpload?connector_name=CONNECTOR_NAME

Accepts a photo uploaded via multipart/form-data to the authenticated user's account for the specified connector.  Currently only supports the Fluxtream Capture connector (specified as "fluxtream_capture" in the query string). The multipart form body must contain two parts:

  • photo: the photo's bytes
  • metadata: JSON containing required photo metadata.  Currently the only required field is "capture_time_secs_utc" which is a double that specifies the time the photo was taken in UTC seconds.  Optional fields are "tags" (a string containing a comma-delimited list of tags) and "comment" (a string). Note that comments and tags are only honored when a photo is uploaded for the first time (a create).  Photos uploaded again are considered an update and the tags and comments are ignored.  Clients needing to modify a Fluxtream Capture photo's tags/comments should use the metadata set API method instead.  Examples:

{"capture_time_secs_utc":1355314332.000}

       {"capture_time_secs_utc":1355314332.000, "tags":"snack,fruit,strawberries", "comment":"Snacked on strawberries from my garden."}

The user need not explicitly add the Fluxtream Capture connector to his/her account prior to upload (and there's actually no way to do so).  Instead, the connector is added automatically upon first upload.  Valid photo formats are JPEG, PNG, and GIF.

See the Fluxtream Capture Photo Architecture docs for more info.

Example: curl -v -u username:password --form 'metadata={"capture_time_secs_utc":1355314332.000}' --form photo=@orientation_4.jpg http://fluxtream.org/api/bodytrack/photoUpload?connector_name=fluxtream_capture;

Returns: JSON describing whether the upload was successful.  The HTTP status code will be 200 upon success, and non-200 upon failure.  Here are several examples:

HTTP 200 OK
{"result":"OK","message":"photo created sucessfully!","payload":{"operation":"created","id":42, "key":"1.FluxtreamCapture.photo.2012348.1355414332000_9c2303170b4601917c59449cdecaecaa0ccbd40b6cf26406f07316261da7fe53"}}

HTTP 200 OK
{"result":"OK","message":"photo updated sucessfully!","payload":{"operation":"updated","id":42,"key":"1.FluxtreamCapture.photo.2012347.1355311332000_0dae72b9ee44a61c1a6efe24814cb713026d58fb5af92f91e88cd2a2bf24d41c"}}

HTTP 400 Bad Request
{"result":"KO","message":"Upload failed because the connector [bogus_connector] is unknown"}

HTTP 400 Bad Request
{"result":"KO","message":"Upload failed because photo uploads are currently only allowed for the Fluxtream Capture connector"}

HTTP 400 Bad Request
{"result":"KO","message":"Upload failed because both the \u0027photo\u0027 and \u0027metadata\u0027 parts are required and must be non-null"}

HTTP 400 Bad Request
{"result":"KO","message":"Upload failed because the Multipart was null"}

HTTP 400 Bad Request
{"result":"KO","message":"InvalidDataException while trying to save the photo"}

HTTP 415 Unsupported Media Type
{"result":"KO","message":"UnsupportedImageFormatException while trying to save the photo"}

HTTP 500 Internal Server Error
{"result":"KO","message":"StorageException while trying to save the photo"}

HTTP 500 Internal Server Error
{"result":"KO","message":"Upload failed due to an unexpected exception"}