Anatomy of a Fitbit API Client Application
Any Fitbit API Client application consists of the following three components:
- Fitbit API client,
- Client application,
- Repository of Fitbit user OAuth credentials and data.
Unless qualified otherwise, client refers interchangeably to your application or Fitbit API client (HTTP client library) running in your application capable of making OAuth-authenticated requests.
Fitbit API client
Any Fitbit API client implementation:
- Implements the Fitbit API protocols to authenticate user with Fitbit and retrieve user credentials and user data,
- Uses client credentials acquired from Fitbit.
We provide reference implementation of the Fitbit API client library in Java (Fitbit4J):
You could also have a look at several libraries in other languages submitted by independent developers:
Or consider starting from scratch in PHP or .Net with the help of our example implementations:
The client application
Reference implementation of the Fitbit Client Application consists of following workflows (in some cases, one of them is desktop applications, Subscriptions-API workflow is irrelevant):
- Uses a Fitbit client with credentials acquired from Fitbit,
- Runs on the client's servers and uses the Fitbit client to communicate with the Fitbit API service,
- Retrieves user credentials and data from Fitbit, stores these in a repository and uses them to generate Fitbit content in the interface for its users,
- Subscribes to notifications sent upon an update to a user's resource,
- Receives update notifications from Fitbit at URLs served on the client's servers,
- Upon receiving an update notification from Fitbit, retrieves the corresponding data from Fitbit and updates it in its repository.
Fitbit OAuth user credentials and user data repository
Fitbit API calls require credentials which the client acquires from Fitbit via the OAuth protocol. The client application will need to store these credentials in a repository in order to use them in subsequent calls. Credentials never expire, unless user revokes access for the application from the profile page or you change "Default Access Type" from "Read" to "Read & Write" (giving your application more possibilities to play with user's data than user already authorized you to). Similarly, if the client application subscribes to updates to a user's resources, the client application can store a user's data retrieved from Fitbit in a local repository and use this data to generate content for its users until it receives an update notification.
Reference Java Implementation
In order to demonstrate the concepts listed on this page and in the API documentation, we built a Fitbit API Client reference implementation we named Fitbit Client Example Java Application. The application is written in Java using Spring Framework and accessible at http://example.fitbit.com. The application depends on Fitbit API Java Client (Fitbit4J) as the Fitbit API client. The application runs on the Fitbit domain and uses Fitbit styles for convenience to the developers. Otherwise, it is a standalone 3rd-party application which could be running at any URL.
The main features of the application are:
- Demonstration of proper OAuth authorization workflow,
- Example Resource Access API call to retrieve and display the user's Activities data,
- Demonstration of Subscription API to subscribe to notifications upon an update to the user's Activities on Fitbit,
- Caching of the Activities data retrieved (and using only cached data to build user interface once user subscribes to updates on Activities via Subscription API -- this is the best practice to avoid hitting API Rate Limit),
- Example of updating cached user's Activities upon receiving an update from Fitbit.
The example application uses the Fitbit API Java Client. A user, identified by a cookie, starts in the UNAUTHORIZED state. This means that the user has not authorized the example application on Fitbit. If the user follows the links provided to authorize the application on Fitbit and completes authorization, the application receives first temporary, then token credentials.The application stores the temporary and token credentials it receives from Fitbit in an in-memory (transient, in most cases permanent storage would make much more sense) cache and reuses the cached token credentials to retrieve user's resources and manage subscriptions without user intervention. Once the application receives token credentials for the user, the user's status becomes AUTHORIZED. The user can expire the cached credentials by revoking access for the application on the Fitbit profile page, in which case the status will return to UNAUTHORIZED.
To understand how this features are translated into actual application source code, please investigate complete source code for the Fitbit Example Java Application available under the LGPL license via Github. This should help you start your development (or become a good best practice reference if you are developing in any other language).
Your Application and Fitbit API versions
For Fitbit API resource calls please keep in mind that while we will maintain collections of existing fields as well as their format through the complete lifecycle of version 1, the API is still in BETA and from time to time we may need to extend existing endpoints by introduction of new fields to keep them up to date with improvements to Fitbit platform. So best practice for your application's response parser would be to stay loose and don't fail validation if it sees extra fields.