Welcome to the first WHOOP Developer Platform blog series, where the engineers behind the platform give readers an inside look across three posts!
In early 2020, WHOOP formed partnerships with companies and research institutions interested in our technology. Several of these partnerships required access to WHOOP APIs.
Our team was not ready to undertake building an entire developer platform, but we wanted to learn from these early partners. We decided to grant our partners access to a subset of our internal APIs, minimizing the level of effort from our team. Over the next two years, our developer partners showcased integrations across coaching, fitness, and health using our nascent API support.
Through these partnerships, our team learned how the needs of external developers differ from those of internal developers:
- Developers outside of WHOOP need a stable interface. While we can aggressively internally version APIs when we control both the client and server, we cannot expect external developers to iterate as quickly.
- Developers outside of WHOOP need documentation that allows them to self-service questions. Internally, we can have a hallway conversation when questions arise.
Armed with the lessons learned and proven potential from this experiment, our team set out to specifically serve the needs of external developers in a fully productized experience: the WHOOP Developer Platform. Here we will explore how we served those needs while maintaining a fast pace of internal experimentation.
Setting external API guidelines
As we learned repeatedly, external developers cannot successfully build experiences on top of a changing API. Internal teams were used to iterating quickly, internally versioning APIs aggressively, and experimenting with additional fields on existing APIs.
We changed our mentality around API design with stability and consistency as top priorities, landing on the following guidelines for developing external APIs:
- Do not expose experimental data that may be removed or changed in the future. Once stabilized, we can add the data in future releases but cannot remove it.
- External developers’ exposure to WHOOP is through the app and public articles. APIs must use language consistent with the app experience to ease cognitive friction, even if the internal data type or attribute is named differently.
Our first recommendation contradicts how we want internal teams to operate – we need to experiment constantly to learn from our members! Our solution had to shield external developers from this experimentation.
Decoupling external developers from internal APIs
To decouple our external developers from our internal APIs, we planned to build specific endpoints for external developers. With our initial set of planned external APIs (strain, sleeps, and more) spanning multiple microservices and owning teams, we faced an organizational as well as technical problem.
Rather than push this responsibility to each downstream team, we decided to build a dedicated entry point, or gateway service, for external APIs. This gateway would be built and managed by a single team. This team would have the context and charter to maintain a consistent API interface.
The gateway service calls internal APIs and transforms their responses according to a new rigorous naming convention consistent with the app experience. Each field returned is explicitly added – internal teams can add experimental fields to their APIs without needing to remember to hide that field from external developers.
This gateway architecture comes with costs – each API call incurs an extra network hop. Additionally, our team structure requires more cross-team synchronization for changes, making iteration on the external API slower. Because we aligned our team around the above API guidelines before implementing, we knew additional network latency and slower iteration speed were acceptable to prioritize our stabilization and consistency requirements.
Redesigning our API was just one step in bringing the WHOOP Developer Platform to life. We also created all new documentation and guides, revamped our app management dashboard, and added support for webhooks.
Develop with WHOOP
Want to integrate WHOOP with your app? Check out the Developer Platform at developer.whoop.com to get started – we can’t wait to see what you build!
If you are interested in building infrastructure at WHOOP check out our open positions.