v1 to v2 Migration Guide
This guide provides information for developers migrating from v1 to v2 of the WHOOP Developer API. The v2 API offers several improvements while maintaining compatibility with core functionality.
Overview of Changes
The v2 API provides several improvements over the v1 API:
- More consistent resource paths and naming
- Enhanced data modeling with more precise types
- UUID-based identification for certain resources
- Better client/server error handling
- More consistent pagination behavior
- Improved OpenAPI specifications and documentation
- Recovery activities are included in the Workouts endpoint
Endpoint Changes
| v1 Endpoint | v2 Endpoint | Notes |
|---|---|---|
v1/activity/sleep | v2/activity/sleep | Same structure, but UUID instead of long for sleepId |
v1/activity/workout | v2/activity/workout | Same structure, but UUID instead of long for workoutId |
v1/cycle | v2/cycle | Enhanced with v2/cycle/{cycleId}/sleep relationship |
v1/recovery | v2/recovery | Improved scoring model |
Data Model Changes
Common Changes
- IDs changed from
longtoUUIDfor some resources (e.g., Sleep, Workout) - More consistent Optional handling
- Added
activityV1Idfields to maintain backwards compatibility - Timezone handling standardized to UTC when not specified
Sleep Model
v1: long getId()→v2: UUID getId()for uniquely identifying sleep- Added
Optional<Integer> getActivityV1Id()to maintain backwards compatibility - Enhanced sleep stage information
- More detailed sleep quality metrics
- Improved scoring model with additional fields
Workout Model
v1: long getId()→v2: UUID getId()for uniquely identifying workouts- Added
Optional<Integer> getActivityV1Id()to maintain backwards compatibility with v1 IDs - More consistent handling of Optional fields
- Improved workout scoring model with properly typed Optional values
Cycle Model
- Consistent score state handling between v1 and v2
- Score is only created when all required data is present (avg heart rate, max heart rate, kilojoules, and strain)
- No fallback values for missing data (maintains backwards compatibility)
- Added relationship to Sleep data through
v2/cycle/{cycleId}/sleep
Authentication and Security
- Consistent scope naming and usage
- Same OAuth 2.0 flow with improved token validation
- Security scopes defined as constants in
DeveloperApiConstants(e.g.,READ_SLEEP,READ_CYCLES,READ_WORKOUT)
Migration Steps
1. Update Endpoints
Update your API client to use v2 endpoints instead of v1:
- GET /v1/activity/sleep
+ GET /v2/activity/sleep
- GET /v1/activity/sleep/{sleepId}
+ GET /v2/activity/sleep/{sleepId}
- GET /v1/activity/workout
+ GET /v2/activity/workout
- GET /v1/activity/workout/{workoutId}
+ GET /v2/activity/workout/{workoutId}
2. Update ID Handling
Resource IDs are now UUIDs instead of longs for certain resources:
- long sleepId = 12345;
+ UUID sleepId = UUID.fromString("ecfc6a15-4661-442f-a9a4-f160dd7afae8");
- long workoutId = 56789;
+ UUID workoutId = UUID.fromString("7bfc6a15-5521-612f-b9a4-e274dd7afae9");
Use the activityV1Id field if you need backwards compatibility with your existing IDs.
3. Update Response Handling
Adjust your code to handle the updated data models:
- Check for presence of fields with Optional.isPresent() rather than null checks
- Use Optional.map(), Optional.orElse(), etc. for proper Optional handling
- Use the new field names and structures
- Take advantage of additional fields and relationships available in v2
4. Testing
- Test your integration thoroughly with both v1 and v2 endpoints
- Compare responses for consistency before fully migrating
- Use the v2 API documentation for field details and required parameters
Benefits of Migrating
- More consistent API behavior
- Better data models and relationships
- Improved error handling
- Future features will be added to v2 first
- Long-term support and improvement path
Deprecation Timeline
The v1 API will continue to be supported, but all new features will be added to v2 first. We recommend migrating to v2 as soon as possible to take advantage of improvements and new functionality.