RESTful API

Getting Data

Once you have an {ACCESS_TOKEN}, you can perform authorised requests by passing the token into the HTTP Authorization header. From the client-side, this isn't quite so easy. So there's another option; you can get away with putting your access token in the query string instead. ie. ?access_token={ACCESS_TOKEN}

Once we're authorised, the responses will be in JSON format.

All data request URLs follow the same pattern; https://api.boditrax.com/rest/v2.10/{COLLECTION}/{ENTITY_ID}/{FIELD}. Each directory is optional. Different levels of the directory structure do different things.

Collections

Collections are lists of entities within our API. Each collection has it's own set of permissions:

Collection Entity description Read collection and entities Add entities Edit entities
facilities A gym or other facility that uses boditrax. scan_performer N/A N/A
members A member who has a Boditrax account. front_end or user_management user_management user_management
readings A set of measurements for a member on a certain date. reporting or measurement_analysis N/A scan_performer
accumulations A set of activity data counts for a member between two dates. reporting activity_offload N/A
linkedaccounts A reference to a 3rd party linked account. user_management user_management N/A
scanlicencses A license to perform a number of scans before a certain date. scan_licenser scan_licenser N/A
scanperformers Client-side software that can perform automated body scans. scan_performer scan_performer scan_performer
goals A goal for a member to hit a target value in a certain metric. goal_analysis N/A N/A

For a detailed reference to the collections, please see our Collection Reference.

Selecting Fields

Browsing to the root of a collection in the API will return an array containing the first page of entities in the collection which your {ACCESS_TOKEN} allows you to see.

With no other parameters, each object will contain the default field(s). Usually this is the entity ID.

https://api.boditrax.com/rest/v2.10/members
[
    {
        id: 1
    },                    
    {
        id: 123
    },
    ...
]

If you need more than just the ID, you can request different fields using the fields parameter with a comma separated value. The allowed fields for each collection can be found in our Collection Reference.

https://api.boditrax.com/rest/v2.10/members?fields=id,first_name,last_name
[
    {
        id: 1,
        first_name: "Connell",
        last_name: "Watkins"
    },                    
    {
        id: 123,
        first_name: "Bilbo",
        last_name: "Baggins"
    },
    ...
]

Filtering Entities

To search the entities, you can filter the results using the where parameter.

https://api.boditrax.com/rest/v2.10/members?where=last_name=Watkins

Supported comparison operators include =, !=, >, >=, <, <=. Currently there is no 'or' operator. You can combine multiple where parameters to achieve an 'and' operator.

https://api.boditrax.com/rest/v2.10/members?where=last_name=Watkins

Sorting Entities

This feature is not available yet but will be introduced in a later version.

By default the collections are sorted by the ID. To order the collection by another field, you can add a sort parameter.

https://api.boditrax.com/rest/v2.10/members?fields=first_name&sort=first_name
[
    {
        first_name: "Bilbo"
    },
    {
        first_name: "Connell"
    },
    ...
]

The default sort direction is ascending. To specify the sort direction manually, you can add the asc or desc keywords after the field name.

https://api.boditrax.com/rest/v2.10/members?fields=first_name&sort=first_name+desc

Mutliple fields can be delimited with a comma.

https://api.boditrax.com/rest/v2.10/members?fields=first_name&sort=first_name+desc,last_name

Pagination

This feature is not available yet but will be introduced in a later version.

The response will only ever display the first page of data (usually the first 50 entities). Pagination can be acheived by adding the page parameter. Pagination is 1-based and the default is page 1.

https://api.boditrax.com/rest/v2.10/readings?fields=id,date&page=2.

If more data is available, the link to the next page will be specified in the HTTP Link header.

Link: <https://api.boditrax.com/rest/v2.10/readings?page=3>; rel="next"

Individual Entities

Adding an ID to the URL as another directory after the collection name finds the entity with that ID and returns its data. Getting a member's information is nice and easy:

https://api.boditrax.com/rest/v2.10/members/1
{
    id: 1,
    first_name: "Connell",
    last_name: "Watkins",
    gender: "M",
    dob: "1982-05-05T00:00:00",
    height: 175,
    athletic: false,
    clothes: 1
}

The fields parameter may also be used in this request. If no fields are defined, all non-hidden fields will be returned.

IDs can be the auto-incrementing integers in the id field. In some cases, special IDs can be used too:

https://api.boditrax.com/rest/v2.10/members/me

Individual Fields

You can also get a single field on it's own by adding to the URL e.g. adding /dob get the member's date of birth directly.

https://api.boditrax.com/rest/v2.10/members/1/dob
"1982-05-05T00:00:00"

Some entities have hidden fields e.g. adding /snap gets all the data needed to create a member's snap page:

https://api.boditrax.com/rest/v2.10/members/1/snap
[
    {
        metric: "bodyweight",
        start: 61.4,
        end: 61.9,
        change: 0.5,
        color: "C04F50"
    },
    ...
]

For more information on the different fields of different entities, see our Collection Reference at the bottom of this page.

Adding/Editing Data

Using the same URLs as the above section, you can add and edit data using the POST and PUT HTTP methods respectively. Deleting data is not currently supported in any collection.

Adding to Collections

Using the POST method, we can add a new member to members collection. The content body can either by a JSON object or a URL encoded string, depending on your preference. Make sure you set the Content-Type HTTP header of your request to match your choice: application/json or x-www-form-urlencoded.

The field names are the same as the fields given when getting an entity. If there is an error processing your request, an exception is returned in JSON format.

POST https://api.boditrax.com/rest/v2.10/members
    first_name=Harry&
    last_name=Potter
{
    success: false,
    error: "Error message here"
}

If adding to the collection is a success, you'll receive an HTTP 201 Created status code and the {ENTITY_ID} of the new entitiy will be returned in the JSON response.

POST https://api.boditrax.com/rest/v2.10/members
    first_name=Harry&
    last_name=Potter
{
    success: true,
    id: 4321
}

To add a new member, you will need to use a facility {ACCESS_TOKEN}. The new member will automatically be authorised to the facility.

Editing Entities

Using the PUT method, we can edit an existing member. The content body is very similar to adding a new member, except none of the fields are mandatory. Only the given fields will be changed, the rest will stay as they were.

PUT https://api.boditrax.com/rest/v2.10/members/1
    {
        first_name: "Bob"
    }
{ success: true }

Individual Fields

Using the PUT method on a field endpoint will edit only that field.

PUT https://api.boditrax.com/rest/v2.10/members/1/first_name
"Bob"
{ success: true }

For a detailed reference to the collections, please see our Collection Reference.