Versioning Strategy

Current state

The backend now supports versioned aliases at:

• /api/v1/*

Legacy unversioned endpoints still exist at:

• /api/*

This is intentional to avoid breaking the existing dashboard while the docs and clients migrate.

Recommended direction

Use /api/v1/* as the canonical documented contract.

This creates a stable public contract and leaves room for:

• non-breaking additions within v1
• explicit v2 rollout later
• clearer deprecation and migration guidance

Practical migration plan

1. stabilize the OpenAPI spec in this repo
2. migrate documented endpoints to /api/v1/*
3. move dashboard/frontend usage gradually to the versioned surface
4. later decide when legacy /api/* aliases can be deprecated

Documentation rule

Once versioned paths are introduced, this docs site should track:

• active versions
• breaking changes
• migration guides between versions