Garmin Vendor Example

Overview

Garmin is a real device-brand client — src/health/vendor/device/garmin.cpp, registered as garmin. It’s the most instructive example of Mirobody’s “implement only what’s publicly confirmable, leave the rest an honest stub” rule, because Garmin’s data API is partner-gated and push-based.

This is a vendor::Vendor implementing the shared authorize / fetch / webhook contract; see Vendor System for the interface.

What Garmin’s API shape forces

Aspect	Reality	Effect on the client
Auth	OAuth 2.0 + PKCE (Garmin migrated off OAuth 1.0a); the flow is public	`authorize_url` is a stub — PKCE needs a stateful `code_verifier` that a bare URL builder can’t stash (that belongs in the EHR-style stateful connect layer)
Data delivery	Push-based: Garmin POSTs summaries to a registered webhook; pulls are partner-gated and retain only ~7 days	`fetch` is a stub that explains the model rather than faking a synchronous pull
Webhook signature	Pushes carry no documented signature	`handle_webhook` is a stub — it can’t verify authenticity from public docs
Disconnect	The account-disconnect hook is publicly documented	`revoke` is implemented

So of the six contract operations, Garmin ships exactly one working call — revoke — and three deliberate stubs (fetch, authorize_url, handle_webhook), with list_providers N/A (single brand). This is the intended state, recorded in the file header.

`revoke` — the one wired operation

revoke calls Garmin’s required account-disconnect endpoint, DELETE /wellness-api/rest/user/registration, authenticated with the user’s OAuth 2.0 access token as a bearer:

void revoke(const std::string& /*user_id*/, const std::string& /*provider*/) override {
    if (config().api_key.empty()) {
        throw VendorError(info_.id + ": revoke requires a Garmin OAuth 2.0 access token — set "
                          "MIROBODY_VENDOR_GARMIN_API_KEY (partner-gated; needs approved creds)");
    }
    client::HttpRequest req;
    req.url     = base_url() + "/wellness-api/rest/user/registration";
    req.headers = { "Authorization: Bearer " + config().api_key };
    client::HttpResponse res = client::HttpClient().request("DELETE", req);
    if (res.status < 200 || res.status >= 300) {
        throw VendorError(info_.id + ": revoke failed (HTTP " +
                          std::to_string(res.status) + "): " + res.body.substr(0, 300));
    }
}

The data host defaults to https://apis.garmin.com (override via MIROBODY_VENDOR_GARMIN_BASE_URL).

`fetch` — a stub that explains itself

Rather than the generic “not implemented”, Garmin’s fetch throws a message stating the reason, so a caller learns the model:

std::string fetch(const std::string&, DataDomain,
                  const std::string&, const std::string&) override {
    throw VendorError(info_.id + ": Garmin Health is push-based and partner-gated "
                      "(OAuth2.0). Data is pushed to a registered webhook, not pulled — "
                      "wire the Ping/Pull data endpoints (partner-gated spec) or consume the "
                      "push once approved partner credentials exist.");
}

Metadata (`info()`)

Even with most operations stubbed, the vendor’s VendorInfo is fully populated and queryable without credentials:

i.id                 = "garmin";
i.display_name       = "Garmin Health";
i.positioning        = "Premium wearable brand; partner-gated, push-based Health API";
i.integration_method = "OAuth2.0 + PKCE; push (Ping/Push webhook) delivery; backfill triggers async";
i.docs_url           = "https://developer.garmin.com/gc-developer-program/health-api/";
i.region             = Region::Global;
i.domains            = {DataDomain::Activity, DataDomain::HeartRate,
                        DataDomain::Sleep, DataDomain::BodyMetrics};
i.integrations       = {Integration::Rest, Integration::Webhook};

Configuration

# Garmin partner-gated OAuth 2.0 access token (needed for revoke; data path is partner-gated)
MIROBODY_VENDOR_GARMIN_API_KEY=your_garmin_oauth2_access_token
# optional host override
MIROBODY_VENDOR_GARMIN_BASE_URL=https://apis.garmin.com

Takeaways for your own vendor

Implement what’s publicly confirmable; stub the rest with a reason. A stub that names the missing contract is better than a fabricated one.
A stateful OAuth flow (PKCE) doesn’t fit authorize_url alone — Mirobody keeps such flows in a stateful connect layer (as the SMART-on-FHIR EHR connect service does), not in the URL-builder signature.
VendorInfo should be complete regardless — it powers selection / comparison without a network call.

For a device brand with a fuller implementation, contrast Garmin with Fitbit (src/health/vendor/device/fitbit.cpp), which implements fetch, authorize_url, revoke, and a signed handle_webhook.

Next steps

Vendor System

The contract Garmin implements

Provider Integration

Build your own vendor::Vendor

OAuth Implementation

OAuth 2.0 / PKCE patterns in the vendor clients

Provider Overview

All shipped vendors

​Overview

​What Garmin’s API shape forces

​revoke — the one wired operation

​fetch — a stub that explains itself

​Metadata (info())

​Configuration

​Takeaways for your own vendor

​Next steps

Vendor System

Provider Integration

OAuth Implementation

Provider Overview

Overview

What Garmin’s API shape forces

`revoke` — the one wired operation

`fetch` — a stub that explains itself

Metadata (`info()`)

Configuration

Takeaways for your own vendor

Next steps