# Versions

- `/v1` ne change que par **ajouts** : nouveaux champs, nouvelles routes.
- Une rupture (un champ retiré, un sens changé) se fera en `/v2`, et `/v1` restera **maintenue 12 mois** après l'annonce.
- Chaque changement visible est daté dans l'[historique des versions](/changelog) et augmente la version de la documentation, affichée par `GET /v1/health` :

```json
{ "status": "ok", "api": "1", "version": "1.0.0-preview.12" }
```

`api` est la version de l'adresse (`/v1`), `version` celle de la documentation.

:::tip{title="Ignorez les champs inconnus"}

De nouveaux champs peuvent apparaître dans les réponses sans changement de version de l'adresse. Votre code doit les ignorer plutôt que de refuser la réponse.

:::

## Le contrat OpenAPI

Le contrat exact de l'API, au format OpenAPI 3.1, sert à générer un client ou à l'importer dans vos outils (Postman, Insomnia, Bruno…) :

- [`/openapi.json`](/openapi.json), sur ce portail ;
- `https://api-dev.atwimi.com/v1/openapi.json`, servi par l'API elle-même.