# Politique de versioning API — Veza v1.0

**Référence** : v0.971  
**Contrat stable** : `/api/v1/`

## 1. Routes stables vs beta

| Type | Exemple | Engagement |
|------|---------|------------|
| **Stable** | `/api/v1/tracks`, `/api/v1/auth/*`, `/api/v1/playlists`, `/api/v1/marketplace/*` | Rétro-compatibilité garantie pour v1.x |
| **Beta** | Fonctionnalités derrière feature flag (ex. WEBRTC_CALLS) | Peut évoluer sans préavis en v1.x |

## 2. Politique de dépréciation

- Les routes dépréciées conservent un header `X-API-Deprecated: true` et une date de fin de vie dans la réponse.
- Période de dépréciation : minimum 6 mois avant suppression.
- Documentation : `API_REFERENCE.md` et Swagger reflètent le statut des routes.

## 3. Headers de version

- `X-API-Version: v1` — optionnel, le path `/api/v1/` suffit.
- `Accept: application/vnd.veza.v1+json` — supporté pour content negotiation.

## 4. Engagement rétro-compatibilité v1.x

- Aucun breaking change sur les routes stables pendant v1.x.
- Les ajouts (nouveaux champs, nouvelles routes) sont rétro-compatibles.
- En cas de breaking change : nouvelle version majeure (v2).

## 5. Breaking changes v0.803 → v1.0

- **Pagination cursor** : certains endpoints utilisent `cursor` / `next_cursor` au lieu de `page` / `limit` (v0.931).
- Voir `CHANGELOG.md` pour la liste complète des changements.