# Versioning

Chaque version représente un **contrat stable** : une fois publiée, elle ne change pas de manière incompatible.

Toutes les routes suivent le format :

```bash
https://api.discordtop.net/v{VERSION}/endpoint
```

Exemple : 

```bash
/v7/vote-check
```

## Objectifs du versioning

Le versioning garantit que :

* vos intégrations **ne cassent jamais** après une mise à jour,
* les évolutions majeures sont publiées dans une **nouvelle version**,
* chaque version possède un **comportement stable et prévisible**.

Une version existante n’introduit **jamais** de breaking changes.

## Règles de versionnage

#### - Une version = un contrat stable

Les endpoints d’une version ne changeront pas dans leur logique, leurs paramètres ou leur format.

#### - Les nouvelles fonctionnalités = même version

Ajouter un champ non requis, un nouvel endpoint ou un comportement optionnel **ne crée pas une nouvelle version**.

#### - Breaking changes = nouvelle version

Toute modification pouvant casser une intégration existante entraîne automatiquement :

```bash
/v8/
```

ou toute version supérieure.

#### - Les anciennes versions restent disponibles

Tant qu’une version n’est pas déclarée "deprecated", elle reste 100% fonctionnelle.

## Tableau des versions

<table><thead><tr><th width="174">Version</th><th width="261">Statut</th><th>Description</th></tr></thead><tbody><tr><td><strong>v7</strong></td><td>🟢 Active (version actuelle)</td><td>Première version publique stable de l’API. Inclut l’endpoint <code>/check-vote</code>.</td></tr><tr><td><strong>v6</strong></td><td>🔴 Deprecated / Ancienne génération</td><td>Ancien système interne non documenté, plus destiné à être utilisé.</td></tr><tr><td><strong>v5 et antérieures</strong></td><td>🔴 Indisponibles</td><td>API obsolètes, retirées ou internes.</td></tr></tbody></table>

## Cycle de version

Lorsqu’une nouvelle version est prévue :

1. Une **période de migration** est annoncée (documentation dédiée).
2. La version précédente devient **“deprecated”** mais reste accessible.
3. Une date de retrait est communiquée (optionnel).
4. Plus tard : la version ancienne peut être supprimée.

## Exemple concret

Vous appelez l’API via :

```bash
/v7/vote-check
```

Si une future version introduit des changements incompatibles, vous pourrez choisir explicitement :

```bash
/v8/vote-check
```

Votre intégration restera stable **tant que vous n’aurez pas choisi vous-même** de migrer.

## Compatibilité ascendante

Les éléments suivants **ne créent pas de nouvelle version** :

* ajout d’un nouveau champ optionnel dans la réponse
* ajout d’un nouvel endpoint
* amélioration de la documentation
* correctifs internes sans impact sur le contrat API
* optimisation de performance
* format de date identique (`ISO 8601`)

Ceux-ci sont considérés comme **non-ruptures**.