veza/docs/API_VERSIONING_POLICY.md

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.