Politique de versioning

L'API SOAMTAR suit SemVer sur le préfixe d'URL.

Modèle

https://app.so-amtar.com/{vMAJOR}/...
                         v1, v2, v3

Type de changement	Bump	Compatibilité	Préavis
Patch (1.0.x)	1.0.0 → 1.0.1	100 % compatible	Aucun
Minor (1.x.0)	1.0.x → 1.1.0	Compatible (ajouts uniquement)	Aucun
Major (x.0.0)	1.x.x → 2.0.0	Incompatible	6 mois

Garanties de compatibilité (Minor)

Au sein d'une version majeure (/v1) :

• ✅ De nouveaux endpoints peuvent apparaître à tout moment
• ✅ Des champs optionnels peuvent être ajoutés aux requêtes à tout moment
• ✅ Des champs peuvent être ajoutés aux réponses à tout moment
• ✅ De nouvelles valeurs d'enum peuvent être ajoutées (traitez toujours les enums comme ouvertes dans votre code)
• ❌ Les champs existants ne sont jamais retirés
• ❌ Les noms de champs ne sont jamais renommés
• ❌ Les types ne changent jamais (string → integer interdit)
• ❌ Les codes d'erreur existants ne sont jamais retirés

Cycle de vie d'une version majeure

v1 publiée ──> Annonce v2 (T0)
                  │
                  ├─> Bêta v2 ouverte (T+3 mois)
                  ├─> v2 GA           (T+6 mois)
                  ├─> v1 dépréciée    (T+6 mois)
                  │
                  └─> v1 EOL, fin du support (T+18 mois)

Vous avez 12 mois entre le passage en dépréciée et l'EOL pour migrer.

Annonce d'une version majeure

• Email à tous les marchands en production
• Article détaillé dans le changelog
• Guide de migration (dans cette section) avec le mapping ancien/nouveau
• Outil de comparaison de payloads ancien/nouveau dans le dashboard
• Permanences hebdomadaires de questions-réponses pendant la bêta

Version dans vos requêtes

Codez toujours /v1 (ou la version visée) en dur dans votre client. Ne comptez jamais sur une redirection automatique : nous n'en émettons pas.

// ✅ Bon
const baseUrl = 'https://app.so-amtar.com/v1'

// ❌ Mauvais : nous ne fournissons pas /latest
const baseUrl = 'https://app.so-amtar.com/latest'

Détecter une dépréciation

Toute réponse d'un endpoint déprécié contient :

HTTP/1.1 200 OK
Sunset: Fri, 31 Dec 2027 23:59:59 GMT
Deprecation: true
Link: <https://app.so-amtar.com/docs/v2/migration>; rel="deprecation"

Journalisez ces en-têtes et alertez votre équipe : vous avez encore du temps, mais commencez à planifier.

Champs dépréciés (sans bump majeur)

Un champ peut être déprécié dans /v1 (il continue de fonctionner mais ne sera pas dans /v2). C'est signalé ainsi :

{
  "data": {
    "old_field": "value",
    "new_field": "value",
    "_deprecations": {
      "old_field": "Use new_field instead. Removed in /v2."
    }
  }
}