Versionnement

La version de l'API vit dans le chemin de l'URL :

https://api.boxioo.com/v1/...

v1 est la version majeure actuelle. Les futurs changements cassants arrivent en /v2, qui tourne côte à côte avec /v1 pendant une fenêtre de dépréciation.

Ce qu'on considère comme cassant

Tout changement susceptible de surprendre un client existant :

• Supprimer ou renommer un champ dans une réponse
• Changer le type d'un champ
• Supprimer un endpoint
• Ajouter un nouveau paramètre obligatoire
• Durcir la validation au point de rejeter des payloads auparavant valides
• Changer la signification d'un code d'erreur

Ces changements arrivent dans une nouvelle version majeure.

Ce qu'on considère comme non cassant

Ces changements arrivent dans la version majeure actuelle, à toute release :

• Ajouter un champ optionnel à une réponse
• Ajouter un paramètre optionnel à une requête
• Ajouter un nouvel endpoint
• Ajouter un nouveau code d'erreur (seuls les nouveaux chemins l'émettent)
• Ajouter un nouveau scope
• Assouplir la validation (accepter des payloads auparavant rejetés)

Si vous écrivez votre client pour ignorer les champs JSON inconnus (la plupart des désérialiseurs le font par défaut), les ajouts ne vous cassent jamais.

Politique de dépréciation

Quand nous prévoyons de retirer une version :

1. 6 mois de préavis via le changelog et un email à tous les propriétaires de tenant ayant des clés
2. 3 mois avant l'arrêt : la version dépréciée émet un header HTTP Sunset à chaque appel
3. À l'arrêt : le chemin déprécié renvoie 410 Gone. Les appels à /v1 redirigent (302) vers /v2 uniquement si la forme de réponse est identique (rare pour des versions majeures).

Version émise par le serveur

Chaque réponse porte :

X-Api-Version: 1

Utile pour les logs et l'observabilité. La valeur du header correspond au préfixe du chemin.

Patterns client recommandés

• Épinglez la version dans votre config : const API_BASE = 'https://api.boxioo.com/v1'
• Ne JSON.stringify pas les champs que vous ne reconnaissez pas — passez-les tels quels comme blobs opaques si vous relayez
• Loguez le requestId des enveloppes d'erreur ; citez-le dans les tickets