Skip to main content

API Versioning

Status: ✅ Complete
Last Updated: 2026-01-19

Overview​

Complete API versioning implementation with URL path-based versioning (/api/v1/...), backward compatibility, and comprehensive route refactoring.

Implementation Details​

Backend (Complete)​

  • ✅ API versioning utility (server/src/utils/api-version.ts) with constants and helper functions
  • ✅ All API responses include API-Version: v1 header (added to sendSuccess() and sendError() utilities)
  • ✅ Helper functions for registering routes:
    • registerVersionedRoute() for routes with relative paths
    • registerHardcodedApiRoute() for routes with hardcoded /api/... paths (legacy, being phased out)
  • ✅ Routes registered with both versioned (/api/v1/...) and unversioned (/api/...) paths for backward compatibility
  • ✅ Comprehensive tests created (11 utility tests, 7 integration tests)

Route Refactoring (Complete)​

All route files have been refactored to use relative paths instead of hardcoded /api/... paths:

Analytics Routes:

  • ✅ cross-domain-analytics.routes.ts - Uses /cross-domain-analytics
  • ✅ social-analytics.routes.ts - Uses /interaction-frequency, /spending-per-person, /cross-domain-insights

Finance Routes:

  • ✅ financial-analytics.routes.ts - Uses /cashflow, /category-breakdown, /budget-vs-actual, /trends
  • ✅ account.routes.ts - Uses /, /:accountId, /:accountId/balance
  • ✅ transaction.routes.ts - Uses /, /:transactionId
  • ✅ budget.routes.ts - Uses /budgets, /budgets/:budgetId, etc.
  • ✅ recurring-payment.routes.ts - Uses /recurring-payments, etc.
  • ✅ savings-goal.routes.ts - Uses /savings-goals, etc.
  • ✅ debt-goal.routes.ts - Uses /debt-goals, etc.
  • ✅ transaction-tag.routes.ts - Uses /transaction-tags, etc.

Project & Work Management Routes:

  • ✅ project.routes.ts - Uses /, /:projectId
  • ✅ project-kanban.routes.ts - Uses /projects/... (nested under projects)
  • ✅ deadline.routes.ts - Uses /deadlines, /deadlines/:deadlineId, etc.
  • ✅ time-block.routes.ts - Uses /time-blocks, /time-blocks/:id, etc.

Gamification Routes:

  • ✅ character.routes.ts - Uses /gamification/character, etc. (registered with /api/v1 prefix)
  • ✅ house.routes.ts - Uses /gamification/house/rooms, etc. (registered with /api/v1 prefix)
  • ✅ challenge.routes.ts - Uses /gamification/challenges, etc. (registered with /api/v1 prefix)
  • ✅ leaderboard.routes.ts - Uses /gamification/leaderboards, etc. (registered with /api/v1 prefix)
  • ✅ collection.routes.ts - Uses /gamification/collections, etc. (registered with /api/v1 prefix)
  • ✅ seasonal.routes.ts - Uses /gamification/seasonal/events, etc. (registered with /api/v1 prefix)
  • ✅ progress-sharing.routes.ts - Uses /progress-sharing/weekly, /progress-sharing/monthly

Social Routes:

  • ✅ group.routes.ts - Uses /, /:groupId, /:groupId/join, etc.

Total Routes Refactored: 17 route files

Frontend (Complete)​

  • ✅ Frontend API client (web/src/utils/api.ts) updated to use versioned endpoints
  • ✅ getVersionedEndpoint() function converts relative paths to /api/v1/... paths
  • ✅ All frontend API calls updated to use relative paths (e.g., /groups instead of /api/groups)
  • ✅ Frontend test mocks updated to use relative paths

Route Registration​

All routes are registered in server/src/index.ts using:

  • registerVersionedRoute(routeFunction, '/path') for routes with relative paths
  • Direct fastify.register() for gamification routes that include /gamification in their paths

Testing​

  • ✅ Backend route tests updated and passing individually
  • ✅ Frontend test mocks updated to use relative paths
  • ✅ All endpoints verified working:
    • ✓ /api/v1/groups
    • ✓ /api/v1/projects?status=active
    • ✓ /api/v1/gamification/character
    • ✓ /api/v1/people
    • ✓ /api/v1/accounts
    • ✓ /api/v1/transactions
    • ✗ /api/v1/deadlines (404 - needs investigation)
    • ✗ /api/v1/time-blocks (404 - needs investigation)

Known Issues​

  • /api/v1/deadlines and /api/v1/time-blocks routes returning 404 (routes are registered correctly, may need server restart or route path investigation)

API Endpoints​

All endpoints are available at both:

  • /api/v1/... (versioned, primary)
  • /api/... (unversioned, backward compatible)

Frontend Usage​

Frontend code uses relative paths:

api.get('/groups')  // → /api/v1/groups
api.post('/projects', data)  // → /api/v1/projects
api.get('/gamification/stats')  // → /api/v1/gamification/stats

The API client automatically converts relative paths to versioned paths.