TimeTracker/docs/API_VERSIONING.md

API Versioning Strategy

Overview

TimeTracker uses URL-based API versioning to ensure backward compatibility while allowing for API evolution.

Version Structure

/api/v1/*  - Current stable API (v1)
/api/v2/*  - Future version (when breaking changes are needed)

Versioning Policy

When to Create a New Version

Create a new API version (e.g., v2) when:

• Breaking changes are required:
  • Removing or renaming fields
  • Changing response structure
  • Changing authentication method
  • Changing required parameters
  • Changing error response format

When NOT to Create a New Version

Do NOT create a new version for:

• Adding new endpoints (add to current version)
• Adding optional fields (backward compatible)
• Adding new response fields (backward compatible)
• Bug fixes (fix in current version)
• Performance improvements (no API change)

Current Versions

v1 (Current)

Status: Stable
Base URL: /api/v1
Documentation: See app/routes/api_v1.py

Features:

• Token-based authentication
• RESTful endpoints
• JSON responses
• Pagination support
• Filtering and sorting

Endpoints:

• /api/v1/projects - Project management
• /api/v1/tasks - Task management
• /api/v1/time-entries - Time entry management
• /api/v1/invoices - Invoice management
• /api/v1/clients - Client management
• And more...

Version Negotiation

Clients specify API version via:

1. URL path (preferred): /api/v1/projects
2. Accept header (future): Accept: application/vnd.timetracker.v1+json
3. Query parameter (fallback): /api/projects?version=1

Deprecation Policy

1. Deprecation Notice: Deprecated endpoints return X-API-Deprecated: true header
2. Deprecation Period: Minimum 6 months before removal
3. Migration Guide: Documentation provided for migrating to new version
4. Removal: Deprecated endpoints removed only in major version bumps

Migration Example

v1 to v2 (Hypothetical)

v1 Response:

{
  "id": 1,
  "name": "Project",
  "client": "Client Name"
}

v2 Response (breaking change):

{
  "id": 1,
  "name": "Project",
  "client": {
    "id": 1,
    "name": "Client Name"
  }
}

Migration:

• v1 endpoint remains available
• v2 endpoint provides new structure
• Clients migrate at their own pace
• v1 deprecated but not removed

Best Practices

1. Always use versioned URLs in client code
2. Handle version negotiation gracefully
3. Monitor deprecation headers in responses
4. Plan migrations well in advance
5. Test against specific versions in CI/CD

Implementation

Current Structure

app/routes/
├── api.py          # Legacy API (deprecated)
├── api_v1.py       # v1 API (current)
└── api/            # Future versioned structure
    └── v1/
        └── __init__.py

Future Structure

app/routes/api/
├── __init__.py
├── v1/
│   ├── __init__.py
│   ├── projects.py
│   ├── tasks.py
│   └── invoices.py
└── v2/
    ├── __init__.py
    ├── projects.py
    └── ...

Version Detection

from flask import request

def get_api_version():
    """Get API version from request"""
    # Check URL path
    if request.path.startswith('/api/v1'):
        return 'v1'
    elif request.path.startswith('/api/v2'):
        return 'v2'
    
    # Check Accept header
    accept = request.headers.get('Accept', '')
    if 'vnd.timetracker.v1' in accept:
        return 'v1'
    elif 'vnd.timetracker.v2' in accept:
        return 'v2'
    
    # Default to v1
    return 'v1'

Documentation

• OpenAPI/Swagger: Available at /api/docs
• Version-specific docs: /api/v1/docs (future)
• Migration guides: In docs/api/migrations/

---

Last Updated: 2025-01-27
Current Version: v1
Next Version: v2 (when needed)