Keep it Simple and SMART (KiSS)

Authors: Jared Fuchs, Melody Spencer, Sukhendu Chakraborty

Introduction: 

As part of the e-commerce and tools team at Fitbit one of our missions is to enable other teams by providing an extensible framework for surfacing device/application data to whoever needs it. Towards that goal, we have provided a common set of APIs that any team can implement that gives internal clients an easy way to view the status of a system or feature. This data is then exposed in easy to use internal tools supported by this framework. 

Motivation: 

Fitbit is a fast paced company with the mission to make the world a healthier place. As part of this goal, it is paramount that we as teams are efficient and self-sufficient to enable our users with critical information about their health and well being. The Core Tools team aims to make business processes efficient by providing the correct amount of information in a most effective and intuitive fashion to the data consumers within the organization. To achieve these objectives our team has conceptualized and implemented a generic SMART API framework to empower teams to expose information they own to the consumers that would like to use it. The name is inspired by Self-Monitoring, Analysis and Reporting Technology, a tool used for surfacing the health of hard drives in computers. At its simplest, the SMART API framework defines a standardized set of HTTP APIs designed to expose the right amount of information at the right level of detail.

UI Design: 

We have come up with a generic UI design which is robust enough to accommodate the data visibility needs for various product teams like Heart rate monitoring, Sleep stage detection, e-Commerce, Fitbit Health Solutions etc. The UI (see below) consists of 3 panels: Status, Summary and Timeline. Each panel below represents one of the APIs a team implements. Once one or more (potentially all) of the APIs are implemented, they come together to provide the most value in the “Analysis” part of data processing. 

APIs:

The following APIs form the core of the framework that teams need to implement to integrate with SMART gateway. 

Status

The status endpoint returns a list of high level indicators relating to a given service or feature and its health. The UI then exposes the various statuses to give a quick overview of what features may need attention. Statuses are implemented and displayed as a color system: 

• Green: The feature is working as intended
• Yellow: There may be an issue with the feature
• Red: There are problems with this feature
• Gray: The given feature is not applicable

Each status also gives a brief description of why it is of  the chosen color.

Example:

“No storage reserved for personal music” (Personal Music, Red)”

Summary

The summary endpoint contains an arbitrary list of key-value pairs that summarize the state of the feature for the given user. This can be used to display aggregates or settings around a given feature. 

Example of summary key/value pairs:

“Completed feature onboarding”: false

Timeline 

The timeline endpoint contains a detailed list of events that drive a given feature or service. It is the most detailed of the endpoints, and therefore is only used when serious analysis is required. The only requirement is that each event has a timestamp. Other event details are up to the implementers. The column name and values are dynamically displayed in a table form in the UI based on the API payloads. 

Example event log:

Event TimeEvent TypeSerial NumberTracker Event Type2020-01-30T22:10:51ZTracker Event1234567890TRACKER_PAIRED

Funnel Approach:

These APIs are used to greatly simplify diagnosability using the UI tool by using a funnel approach to provide the  information needed to quickly narrow in on any potential problems being experienced. When we drill down further into the summary information, this helps tell the story of the issue. For example (see image below) If there is a “Red” failure on the battery, it may show up as average discharge time of their battery (summary trends) being much shorter than normal leading to quick diagnosis of their problem. If the summary details are not enough to pinpoint the issue, we can quickly load up the timeline (detailed annotations) portion to see all the battery annotations for that device in the Timeline Debug portion.

Implementation: 

At Fitbit, most of our service infrastructure communicates internally via Apache Thrift (http://thrift.apache.org/) using the Finagle stack (https://twitter.github.io/finagle/) and many of the services we need to support do not expose HTTP endpoints that are usually more conducive for web clients. In order to make integration as easy and painless as possible, we created the Smart Gateway microservice in order to translate internal endpoints communicating via Thrift to web endpoints communicating via HTTP. This allows for those thrift endpoints to be easily consumed by our tools webpage as well as other custom platforms. For teams looking to integrate with Smart Gateway (and therefore provide SMART APIs), all they need to do is to implement a Thrift server matching the SMART API specification. Smart Gateway then registers an appropriate set of URLs that proxy the Thrift Server to our API domain.

Feature teams are free to implement as much of the SMART API specification in their Thrift server as it makes sense for them. Most teams find that their integration with Smart Gateway ends up taking less than a day of work. Furthermore, by pushing the responsibility of API implementations onto feature teams, they have the power to update the content of their SMART API responses on their own deployment schedules leading to development agility. 

Currently, these APIs help quite a few teams with their numerous data diagnosis use cases. We already have over 25 integrations and counting. 

Conclusion: 

We have discussed how a simple approach of a robust UI together with a generic API design can help improve cross team collaboration, self sufficiency and efficiency. At Fitbit we constantly aspire to innovate not only to improve our user’s fitness and health tracking but also to come up with solutions internally to empower and enable teams to provide the best possible work experience.