Migrate off a deprecated fitness API

Migrate off a deprecated fitness API

A fitness or health provider has announced it is sunsetting the API you depend on, and you need to move before the hard turndown. The move is a real re-integration, not a config swap: you adopt a successor product with a new data schema and — almost always — a new auth model, and in most cases every user has to reconnect because access tokens do not carry over. The single biggest silent gap is historical data, since a successor store often holds only recent or on-device data and back-fill is limited. This page is the reusable playbook for any deprecation; the two live examples below (Google Fit, Fitbit Web API) each have their own detailed guide.

Deprecations tend to follow the same shape: the vendor freezes new sign-ups, announces a successor plus a timeline, opens a parallel-run window, then hard-turns-down the old API. Google Fit froze new sign-ups on May 1, 2024 and is stated to be supported only through the end of 2026 (verify the exact date); the legacy Fitbit Web API is being retired in favor of a Google-built cloud API during a 2026 side-by-side window (verify current Fitbit/Google developer notices). Your job is to run the successor in parallel with a rollback path and move users in waves before the old door closes.

If your specific trigger is Google Fit, start with the symptom page /fix/google-fit-api-deprecated and the full move in /migrate/google-fit-to-health-connect; the sequence below generalizes those to any provider.

What actually changes

The successor is rarely a drop-in. Expect changes on three axes — architecture, auth, and data shape — plus a history gap. State each fairly for your specific move.

Two recurring truths worth repeating: on-device successors (Health Connect on Android, HealthKit on iOS) are on-device stores with no cloud endpoint, so a backend that read data server-to-server must re-architect; and how far back you can back-fill is set by each underlying provider, not by you. For the concept behind that architecture shift, see /learn/on-device-vs-cloud-health-data.

The migration, step by step

Adapt the sequence to your specific move, but keep the order — parallel-run and rollback are what keep users connected.

1. Inventory what you use. Enumerate every endpoint, data type, and scope, whether each read/write happens on the client or server, and your user count per integration. This map is what turns the next migration into a lookup instead of a scavenger hunt.
2. Find the official successor and migration notice. Go to the vendor's primary developer docs — not blogs — for the successor product, the migration guide, and the freeze/parallel/turndown timeline. Record every date and mark it "verify," because vendor timelines move.
3. Map data and auth models. Build a field-by-field data mapping (old data type → new record type/field) and an old-auth → new-auth mapping side by side. Flag any missing data types and any architecture shift, such as cloud → on-device.
4. Stand up the new integration in parallel. Build the successor path alongside the old one and keep the old path live through its support window. Put an abstraction layer over your health-data service so the rest of the app does not hard-depend on either provider, and dual-read to compare values.
5. Back-fill historical data within limits. Pull whatever history the new source and its permissions allow (on-device stores often gate history behind a dedicated permission and a short default window — verify). Accept and document that deep history may not be recoverable.
6. Run a user re-consent / reconnect flow. Design clear UX for re-authorization — new OAuth sign-in or OS permission grant — and reconcile the new provider user id back to your user. Do not force-disconnect the old source prematurely; let old-path data keep flowing until each user reconnects.
7. Migrate in waves with a rollback path, and monitor. Move users in cohorts, not a big-bang cutover. Watch auth-failure, sync-gap, and permission-denied rates, compare old vs new values per cohort, and keep the ability to fall back until confidence is high.
8. Decommission the old integration. Only after the wave migration is validated — and before the vendor's hard turndown — retire the old path. Chase non-reconnected users with reminders first.

Gotchas and how to keep users connected

The continuity risks are predictable, so plan for them from day one:

• Lost connections. OAuth grants and refresh tokens are bound to the old app or aggregator; the new path always needs a fresh authorization. Assume mandatory re-consent — never promise a zero-touch migration. For the reconnect-UX details, see the companion playbook /migrate/keep-users-connected-during-migration.
• Data gaps. If you hard-cut, data stops while users are mid-reconnect. Dual-read old and new in parallel and reconcile gaps against the old path.
• Tokens that do not transfer. Because the OAuth provider or library changes, there is no silent migration of consent. Design the re-auth prompt as a first-class flow, not an afterthought.
• Historical-data limits. Back-fill depth is provider-capped and, on on-device stores, permission-gated. Verify each provider's current cap and set user expectations rather than promising full history.

Aggregator as insulation, and reducing future exposure

If you would rather not absorb the re-integration yourself — or want to avoid the next one — a health-data aggregator covers many providers behind one API or SDK. When an upstream provider deprecates, the aggregator absorbs the change and you keep a single contract. The trade-offs are honest ones: recurring cost, trusting a third party in your data path, and coverage or field-normalization limits (a unified schema can drop provider-specific fields — verify raw passthrough if you need them). Vendor examples such as Terra, Validic, Junction (formerly Vital), Rook, Spike, and Thryve/Sahha are illustrative, not endorsements — verify current provider coverage. See /fitness-apis/health-data-aggregator-apis for how the category works.

To reduce future deprecation exposure regardless of which path you pick: put an abstraction layer between your app and any provider so swaps stay localized; normalize to your own internal schema instead of storing vendor-shaped data; keep provider-specific quirks out of business logic; subscribe to each provider's deprecation and developer notices; prefer OS-blessed on-device stores where they fit; and keep the inventory doc from step 1 current so the next migration starts from a map.

Bottom line

Budget a deprecation migration as a real re-integration: new schema, new auth, mandatory re-consent, a parallel-run window, and a partial history back-fill — not a URL swap. Move in waves with rollback, and decommission only after the successor is validated. Because vendor timelines and data-type coverage shift, verify every date and every mapping against the provider's current primary docs before you cut over.