Minor: No API Versioning Strategy

[AliiiBenn]

Priority

🟡 Minor - API Design & Maintainability

Locations

• src/app/(payload)/api/[...slug]/route.ts
• src/app/(frontend)/api/auth/[...all]/route.ts
• All custom API routes

Problem Description

API routes lack versioning, making future breaking changes difficult.

Issues

1. Breaking Changes Break Clients

Cannot make breaking changes without breaking existing clients.

2. No Backward Compatibility

Cannot maintain multiple API versions.

3. No Migration Path

Clients don't know when API changes, no deprecation warnings.

4. Testing Challenges

Cannot test old vs new API versions.

Expected Behavior

Option 1: URL Path Versioning (Recommended)

/api/v1/lessons/:id
/api/v2/lessons/:id

Create directory structure for v1, v2, etc.

Recommendation: URL Path Versioning

Directory Structure

src/app/api/
├── v1/
│   ├── compile/
│   ├── lessons/
│   └── progress/
├── v2/
│   └── ...
└── route.ts  ← Redirect /api to /api/v1

Migration Strategy

Phase 1: Add v1 Structure (Non-breaking)

Move existing routes to /api/v1/, add redirect from /api to /api/v1

Phase 2: Add v2 (Non-breaking)

Create /api/v2/ with new implementation

Phase 3: Deprecation Warning

Add deprecation header to v1

Phase 4: Remove v1

After sunset date, remove v1

Related Issues

• Minor: Empty Package Name in package.json #19 - No API documentation
• #033 - TypeScript not strict enough

Steps to Fix

1. Create /api/v1/ directory structure
2. Move existing routes to v1
3. Add redirect from /api to /api/v1
4. Document API versioning in API.md
5. Add version header to all responses
6. Plan for v2 when breaking changes needed

Additional Context

This may seem premature for a new project, but establishing versioning early prevents pain later. The project already has multiple API consumers (web app, potentially mobile apps, etc.) and breaking changes will be needed.