Version 2.2.1 - Breaking Changes Release

Released: November 15, 2024
Status: Stable
Type: Breaking Change
Migration Deadline: February 15, 2025

Important

This release contains breaking changes that require action from API users and third-party integrations. Please review the migration guide carefully.

⚠️ Breaking Changes Overview

This release restructures core APIs and data models to improve performance and enable future features. While we've tried to minimize disruption, some changes require updates to existing integrations.

🔴 Critical Breaking Changes

1. Authentication Flow Changes

What Changed

Migrated from Firebase Auth to hybrid authentication system supporting multiple providers.

Before (Deprecated)

// Old authentication
const auth = firebase.auth();
const user = await auth.signInWithEmailAndPassword(email, password);
const token = await user.getIdToken();

After (Required)

// New authentication
const response = await fetch('/auth/login', {
  method: 'POST',
  body: JSON.stringify({ email, password })
});
const { accessToken, refreshToken } = await response.json();

Migration Steps

1. Update authentication endpoints
2. Store refresh tokens securely
3. Implement token refresh logic
4. Update authorization headers

Impact

• Affected Users: All API integrations
• Migration Effort: Medium (2-4 hours)
• Deadline: February 15, 2025

---

2. Habit Data Structure Redesign

What Changed

Complete restructuring of habit objects to support new features like habit templates and AI coaching.

Old Structure (Deprecated)

{
  "id": "habit_123",
  "title": "Morning Run",
  "frequency": "daily",
  "target": 1,
  "unit": "times",
  "streak": 15,
  "completedDates": ["2024-11-01", "2024-11-02"]
}

New Structure (Required)

{
  "id": "habit_123",
  "name": "Morning Run",
  "occurrence": {
    "type": "daily"
  },
  "goals": [{
    "periodicity": "daily",
    "value": 1,
    "unit": "rep"
  }],
  "statistics": {
    "currentStreak": 15,
    "bestStreak": 30,
    "totalCompletions": 150
  }
}

Field Mapping

Old Field	New Field	Notes
title	name	Direct rename
frequency	occurrence.type	Now nested object
target	goals[0].value	Now array of goals
unit	goals[0].unit	Standardized units
streak	statistics.currentStreak	Moved to statistics
completedDates	(removed)	Use /logs endpoint

Impact

• Affected Users: All users
• Migration Effort: High (4-8 hours)
• Auto-migration: Partial (read-only backwards compatibility)

---

3. API Endpoint Restructuring

Removed Endpoints

DELETE /api/v1/habits/bulk       → Use batch operations
GET /api/v1/habits/today         → Use /habits?date=today
POST /api/v1/habits/checkin      → Use /habits/{id}/logs
GET /api/v1/user/statistics      → Use /statistics/overview
POST /api/v1/habits/skip         → Use /habits/{id}/logs/skip

Changed Endpoints

/api/v1/habits → /api/v2/habits
/api/v1/logs → /api/v2/habits/{habitId}/logs
/api/v1/notes → /api/v2/habits/{habitId}/notes
/api/v1/statistics → /api/v2/statistics
/api/v1/areas → /api/v2/areas

New Required Headers

X-API-Version: 2
X-Client-Version: (your app version)
X-Request-ID: (unique request identifier)

---

4. Response Format Standardization

Old Response Format

{
  "success": true,
  "data": { ... },
  "error": null
}

New Response Format

{
  "data": { ... },
  "meta": {
    "requestId": "req_xyz",
    "timestamp": "2024-11-15T10:00:00Z",
    "version": "2.2.1"
  },
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0
  }
}

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  },
  "meta": { ... }
}

---

🟡 Deprecated Features

Will be removed in v3.0 (July 2025)

1. Legacy Authentication

   • Firebase ID tokens still accepted but deprecated
   • Migration to API keys recommended

2. Old Webhook Format

   • v1 webhook payloads deprecated
   • Update to v2 format with typed events

3. CSV Export v1

   • Old CSV format will be removed
   • New format includes additional fields

4. Manual Sync

   • Sync button removed in favor of automatic sync
   • Real-time sync via WebSocket available

🟢 New Features Requiring Migration

Habit Templates

{
  "templateId": "template_morning_routine",
  "habits": [
    { "name": "Drink Water", "occurrence": { "type": "daily" } },
    { "name": "Meditate", "occurrence": { "type": "daily" } },
    { "name": "Exercise", "occurrence": { "type": "daily" } }
  ]
}

Batch Operations

POST /api/v2/batch
{
  "operations": [
    { "method": "POST", "path": "/habits/habit1/logs", "body": { ... } },
    { "method": "POST", "path": "/habits/habit2/logs", "body": { ... } },
    { "method": "PUT", "path": "/habits/habit3", "body": { ... } }
  ]
}

📊 Migration Statistics

As of November 30, 2024:

• Total API Users: 15,420
• Migrated to v2: 8,234 (53.4%)
• Partially Migrated: 3,421 (22.2%)
• Not Started: 3,765 (24.4%)

🛠 Migration Tools

Automated Migration Script

npm install -g @habitify/migration-cli
habitify-migrate --from v1 --to v2.2.1 --api-key YOUR_KEY

Migration SDK

import { HabitifyMigration } from '@habitify/migration-sdk';

const migration = new HabitifyMigration({
  apiKey: 'YOUR_KEY',
  version: '2.2.1'
});

await migration.run();

Testing Endpoints

• Sandbox: https://sandbox.habitify.me/api/v2
• Validator: https://api.habitify.me/validate

📅 Timeline

Date	Event
Nov 15, 2024	v2.2.1 released
Dec 1, 2024	Migration tools available
Jan 1, 2025	Deprecation warnings start
Feb 15, 2025	v1 API sunset
March 1, 2025	v1 completely removed

✅ Migration Checklist

• Review all breaking changes
• Update authentication flow
• Migrate habit data structures
• Update API endpoints
• Implement new response handling
• Update error handling
• Test in sandbox environment
• Update production code
• Monitor for issues
• Remove deprecated code

🆘 Support Resources

Documentation

• Complete Migration Guide
• API v2 Reference
• Code Examples

Get Help

• Email: api-support@habitify.me
• Discord: #api-migration channel
• Office Hours: Tuesdays 2-4 PM PST via Zoom
• Priority Support: Available for Premium/Enterprise

FAQs

Q: Will my app break immediately?
A: No, v1 API remains functional until February 15, 2025.

Q: Can I use both v1 and v2 simultaneously?
A: Yes, during the migration period you can use both.

Q: What if I can't migrate by the deadline?
A: Contact support for an extension (case-by-case basis).

Q: Are there any costs for migration?
A: No, migration tools and support are free.

🎯 Why These Changes?

1. Performance: 3x faster response times
2. Scalability: Support for 10M+ users
3. Features: Enable AI, templates, and real-time sync
4. Security: Enhanced authentication and encryption
5. Consistency: Standardized API patterns

---

Migration Tip

Start with authentication changes, then move to data structure updates. Test thoroughly in sandbox before production deployment.

Final Notice

After February 15, 2025, all v1 API calls will return 410 Gone status. Please complete migration before this date.