Data Sources

A Data Source is a feed of data that comes from a particular provider for a specific type of data.

Listing Data Sources

To learn the data sources that exist or to find the id of your desired data type, you will need to issue a list.

curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/providers/sources/"

Request Parameters

None

Response

The response will be a 200 with a JSON body that contains the List Source Data. See the Data Types section for a description.

Example JSON

{"items": [{
    "name": "My Health Data",
    "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
    "type": "Activity",
    "enabled": true,
    "providerType": "Withings"
}]}

Notes

The above will not contain entries from the FitnessSyncer Notebook. You must query for those separately.

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire the full list data sources from all participants using this API.

Get a Specific Source

If you have an id to a specific source item, you can easily acquire the configuration of that item easily.

curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/providers/sources/id"

Request Parameters

None

Response

The response will be a 200 with a JSON body that will contain a Source Data Item. See the Data Types section for a description.

Example JSON

{"item": {
    "name": "My Health Data",
    "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
    "type": "Activity",
    "enabled": true,
    "providerType": "Withings"
}}

If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s data source.

Creating new Data Sources

To create a new Data Source, one must issue a PUT request with that configuration.

Please see Provider Authentication to configure authentication for your source.

The user can also change this item using our editor. It is recommended that you only cache this data temporarily.

Request Parameters

The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the new item.

Setting up a CSV Source or Destination

A CSV source or destination needs two things an ordinary one does not: a file format of CSV, and a column mapping saying which column of the file feeds which of our fields. Both live in CSV Provider Config, sent as the csv section of Provider Config when you create the source.

Do not hard-code the file formats or the column names. Both are served by the Descriptions API in the language of the request, and both grow over time, so a client that embeds them goes stale.

The steps

1. Ask GET /api/descriptions/fileFormats?taskType=Activity&direction=SOURCE which formats the chosen data type supports. An entry whose requiresColumnMapping is true, which is CSV and CSV_PRESET_LAP_SUMMARY, cannot be used without the mapping in step 3.
2. Ask GET /api/descriptions/csvColumns?taskType=Activity&direction=SOURCE for the columns you may map. Each carries a key to send back, a description in the user’s language to show them, and a group for arranging a picker into sections.
3. Read the header row of the user’s own file and pair each of its columns with one of ours. Build one entry per mapped field in csv.columns, giving the column key and the index of the file column that feeds it.
4. Create the Data Source with a PUT, sending providerConfig.maps.fileFormat of CSV, the path to the file, and your providerConfig.csv section.
5. Authenticate the source so we can reach the file, then Refresh it to read the file for the first time.

Column numbering

The first column of the file is 1, which is the numbering the FitnessSyncer editor shows the user. An index of 0 means the row supplies no column at all, so a row carrying only a defaultValue may send 0 or omit the field entirely. This matters because a generated client whose integers are not nullable sends 0 for a field it never set, and that must not be read as the first column.

Default values

A row may carry a defaultValue instead of, or alongside, an index. On a source it supplies a constant for a field the file has no column for; on a destination it writes that constant into the column. A row with neither an index nor a default value does nothing.

Replacing the mapping

Sending a columns array replaces the stored mapping in full rather than merging into it, so a client removing one row sends the whole remaining set. Leaving the array out entirely keeps the mapping that is already stored, which lets you change a dialect setting such as the separator without resending the mapping.

Destinations

A destination is the same sequence against https://api.fitnesssyncer.com/api/providers/destinations/, asking both Descriptions calls with direction=DESTINATION. The direction matters: it decides which columns apply, and CSV_PRESET_LAP_SUMMARY is offered only for destinations because it is a fixed layout we write rather than one we can read.

Updating Data Sources

To update a Data Source, one must issue a POST request with that configuration.

Please see Provider Authentication to configure authentication for your source.

Request Parameters

The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.

Response

The Response will be a JSON body with an id field indicating the ID of the updated item.

Deleting Data Sources

When you are finished with a data source, simply delete it. This operation cannot be undone.

curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/providers/sources/id"

Request Parameters

None

Response

The Response will be a JSON body with an id field indicating the ID of the deleted item.

Refreshing Data Sources

FitnessSyncer will periodically refresh data sources. If your application wishes to ensure that you have the latest data available, you can request a refresh.

When this operation completes, the task is enqueued and will execute sometime in the near future. You may check on the status of the task via the Sync Status API.

Note: This is only available on certain accounts. Please contact us if you require it.

Request Parameters

None are required.

If the user is a FitnessSyncer Pro, you may issue a Historic Sync request.

Response

On success, this will return a 202 with a JSON body indicating the id of the item enqueued.

In the event that there is already a pending request for this user, a 409 will be returned to you.

Getting Historic Sync Status

FitnessSyncer Pro users have the ability to request historic syncs to get data from the past for many providers, primarily those where we initially fetch only the last 30 or 90 days. You can request a Historic Sync through a Refresh. This API returns the current status of any ongoing or completed historic syncs.

curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/providers/sources/id/historicSync"

Response

The Response will be a JSON body with an items field containing a Historic Sync Status.

In the event that there is already a pending request for this user, a 409 will be returned to you.

Synchronization Status

The Source Refresh and Destination Task Execute APIs operate asynchronously. This API lets you check on the current status of those queued tasks.

Getting Synchronization Status

Returns the current synchronization status for all active tasks associated with the user’s account, including in-progress refreshes and destination executions.

curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/syncs/"

Request Parameters

None

Response

The Response will be a JSON body with a Sync Status result.

Notes

The results are filtered to which scopes your token may read. With source_read you receive the Source entries, with destination_read you receive the Destination entries, and with both you receive both. If you have neither scopes, it will result in a 401.

Types

List of Source Data

Source Data Item

Historic Sync Request

This is an optional request body to the Refresh Data Source.

Historic Sync Status

This is an response body to the Get Historic Sync Status.

Source Data

This structure defines the Source Data.

At this time, filters are not configurable via the API. Other fields may be included in the future and should be ignored.

Sample

{
    "name": "My Health Data",
    "id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
    "type": "Activity",
    "enabled": true,
    "providerType": "Withings"
}