11 lines
753 B
Markdown
11 lines
753 B
Markdown
|
# API versioning
|
|||
|
|
|
|||
|
|
- **Current:** All REST APIs are under **`/api/v1`** (sync, pull, delete, health, info).
|
|||
|
|
- **When to introduce v2:** When you make **breaking changes** (e.g. remove or rename request/response fields, change semantics, or drop support for old clients).
|
|||
|
|
- **How to add v2:**
|
|||
|
|
1. Add new controllers or paths under **`/api/v2`** with the new contract.
|
|||
|
|
2. Keep `/api/v1` working for a documented **deprecation period** (e.g. 6–12 months).
|
|||
|
|
3. Document in OpenAPI and in response headers, e.g. `X-API-Deprecated: true`, `Sunset: <date>`.
|
|||
|
|
4. Update clients (Android, iOS, Web) to use v2 before sunset; then remove v1.
|
|||
|
|
- **Non-breaking changes** (new optional fields, new endpoints) do **not** require a new version; keep them in v1.
|