Checking for Data Updates: Implementation Guide¶

This guide explains how to synchronize data from the Firstbeat Sports Cloud API to your application. It focuses on detecting new data (such as added measurements, sessions, or laps) and updated data (such as a coach adding athletes to a session or editing properties).

API Limitations¶

The Firstbeat Sports Cloud API does not include a lastModified or updatedAt timestamp for filtering. You cannot request "records that have changed since [date]." The API also lacks webhooks to notify users of updates.

These are known limitations that we hope to improve soon.

Instead, the API supports date filtering based on the start time of measurements and sessions. Design your synchronization logic around this.

Update vs. Sync¶

Distinguish between two types of API resources:

1. Update endpoints: These return lists of available data (e.g., IDs and basic properties). They are fast, especially with asynchronous calls and a Token Bucket rate-limiting algorithm. Use them to identify what needs syncing.

   Examples of data fetched:

   • Athletes
   • Measurements (athlete-specific)
   • Coaches (skip if not needed)
   • Teams and groups, including athlete memberships (via the teams endpoint)
   • Sessions and associated measurements
   • Session laps (use includeLaps=true with sessions)
   • Measurement laps (use includeLaps=true with measurements; not commonly used?)

For an account with 20 athletes (each with under 100 measurements) and under 1,000 sessions, this requires about 20-30 API calls.

1. Sync endpoints: These return detailed analysis results for the data. Perform them only for new or changed items to avoid unnecessary load.

   Examples:

   • Measurement results
   • Measurement lap results (if used; most teams skip this)
   • Session results
   • Session lap results (if used)

Example Workflow¶

Combine "Update" and "Sync" using these steps:

1. Update Phase¶

Request lists to get IDs, timestamps, and basic properties for change detection.

• Athletes: GET /sports/accounts/{accountId}/athletes
• Teams: GET /sports/accounts/{accountId}/teams (includes athlete memberships)
• Measurements: GET /sports/accounts/{accountId}/athletes/{athleteId}/measurements (filter with fromTime)
• Sessions: GET /sports/accounts/{accountId}/teams/{teamId}/sessions (filter with fromTime)

2. Comparison Logic (Local vs. Remote)¶

Compare API responses to your local database:

• New items: If an ID (e.g., measurementId) is missing locally, mark for sync.
• Changed items: If the ID exists but properties differ (e.g., updated notes or added athlete IDs in a session), mark for sync.
• Unchanged items: If the ID exists and properties match, skip.

3. Sync Phase¶

Fetch results only for marked items:

• Measurement results: GET /sports/accounts/{accountId}/athletes/{athleteId}/measurements/{measurementId}/results
• Session results: GET /sports/accounts/{accountId}/teams/{teamId}/sessions/{sessionId}/results
• Laps: Use lap result endpoints if tracking lap data.

This separation minimizes API usage by avoiding heavy fetches for unchanged data.

Strategy 1: Fetching New Data (Incremental Sync)¶

Use case: Download only new measurements or sessions added since your last sync.

The API's start-time filtering allows "paging forward" through time.

Steps¶

1. Track progress: Store the latest startTime (or sync time) in your database.
2. Request: Use endpoints measurements or sessions with fromTime parameter.
3. Process: The API returns events starting at or after that time.
4. Deduplicate: Since fromTime is inclusive, check IDs to skip existing records.

Pros: Efficient with minimal data transfer. Cons: Misses edits to older records (e.g., notes added to a two-month-old session).

Strategy 2: Do a periodic lookback sync¶

Use case: Capture edits to history or data where changes are not visible via the available params

Re-fetch a time window to make sure all changes are synced. Force re-sync of analysis results.

Steps¶

1. Define a window: Choose a lookback period for likely changes (e.g., last 30 days). Omit fromTime for full history (but avoid if possible, as it's resource-intensive).
2. Process:     - Do a full (forced) sync of all data overnight for the chosen window     - Fetch data again and overwrite your local copies

Pros: Maintains data consistency. Cons: Higher bandwidth and processing; re-downloads known data. Slow.

Best Practices¶

Consider combining different strategies:

• Run incremental syncs frequently for new data.
• Run lookback syncs nightly or before known important reporting times.

API Rate Limits¶

The throttling uses a Token Bucket algorithm: Burst up to 60 requests quickly, then refill at 1 token per second. Implement asynchronous calls for bursts (e.g., 20-40 at once) to speed updates.

To request higher limits or quotas, contact Cloud API support with your needs. We can often adjust, provided responsible usage, as the API shares resources with production systems.

Handling data deletions¶

Coaches can delete data on the account. This includes measurements, sessions laps, athletes, teams etc. How this is handled on the Client side needs to be decided based on the use case and need.

Firstbeat Sports cascades data deletions to maintain data consistency.

• If athlete is deleted, all the athlete measurements are also deleted.
• If athlete measurement is deleted, it's automatically removed to any sessions it might be added to.
• If session is deleted, all relateed session laps are deleted.
• Etc.

Details¶

• In rare cases, changes like updated min/max HR (triggering re-analysis) alter results (e.g., TRIMP values) without changing IDs or properties. Detect these only via periodic full syncs. This is a known API limitation.
• It's possible to move (transfer) a measurement to another athlete. In this case, the measurement ID stays the same but the athlete ID changes. This is rare, but can happen.
• It's also possiblle to change the start time (or date) of a measurement. In this case, all other data stays the same but e.g. the date can change.