# Versionnage et stabilité

Comment l’API est versionnée, quels changements peuvent arriver sans nouvelle version majeure, et comment s’épingler à v1.

PDF Blocks versionne l’API pour que vous puissiez adopter les améliorations sans
craindre une rupture surprise. Les règles ci-dessous vous disent exactement quels
changements peuvent vous parvenir automatiquement sans risque, et comment un
changement incompatible vous atteindrait.

## Versionnage sémantique

L’API suit le [versionnage sémantique 2.0.0](https://semver.org). Pour un numéro
de version `X.Y.Z` :

| Partie | Nom       | Signification                                |
| ------ | --------- | -------------------------------------------- |
| `X`    | Majeure   | Changements incompatibles avec l’existant.   |
| `Y`    | Mineure   | Ajouts de fonctionnalités rétrocompatibles.  |
| `Z`    | Correctif | Corrections de bugs rétrocompatibles.        |

La version actuelle de la spécification est `1.18.0`. Vous pouvez toujours lire
la version en vigueur dans le champ `info.version` de la
[Spécification OpenAPI](/docs/api/openapi-specification).

## La majeure `v1` dans le chemin

La version **majeure** est épinglée dans le chemin de l’URL : chaque action vit
sous `/v1/`, comme dans `https://api.pdfblocks.com/v1/add_text_watermark`. Les
versions mineures et correctives sont livrées sur place sous `/v1/` : vous les
recevez automatiquement et ne changez jamais vos URL pour en profiter. Comme les
changements incompatibles ne sont jamais livrés que sous une nouvelle majeure (un
nouveau segment de chemin), rester sur `/v1/` revient à rester sur un contrat
stable.

## Ce qui compte comme rétrocompatible

Au sein de `v1`, nous faisons des changements additifs sans nouvelle version
majeure. Considérez tout ce qui suit comme pouvant apparaître à tout moment, et
écrivez des clients qui le tolèrent :

- **De nouveaux paramètres optionnels** sur une action existante.
- **De nouvelles valeurs acceptées** pour un paramètre existant, c’est-à-dire une
  énumération élargie.
- **Des alias de paramètres**, un nouveau nom pour un champ existant, l’ancien
  nom restant accepté.
- **Des réponses plus riches**, avec de nouveaux champs dans un corps de réponse
  ou de nouveaux en-têtes de réponse.
- **De nouvelles actions et de nouveaux endpoints.**

Aucun de ces changements ne vous oblige à épingler une version mineure ni à
modifier votre code. Pour rester compatible, ignorez les champs de réponse que
vous ne reconnaissez pas au lieu d’échouer dessus, et ne supposez pas qu’une
énumération soit un ensemble figé et exhaustif.

## Comment les changements incompatibles sont livrés

Un changement incompatible, qu’il s’agisse de supprimer ou de renommer un
paramètre obligatoire, de modifier une réponse de façon incompatible ou d’altérer
un comportement établi, ne serait livré que sous la forme d’une **nouvelle
version majeure sur un nouveau chemin**, par exemple `/v2/`. Vos appels `/v1/`
existants continuent de fonctionner à l’identique, et vous migrez à votre rythme.
Nous ne faisons pas de changement incompatible sur place sous `/v1/`.

## S’épingler à une majeure

Épinglez votre intégration à la majeure `v1` en gardant `/v1/` dans les URL de
vos requêtes. C’est tout l’épinglage dont vous avez besoin : vous recevez
automatiquement les améliorations mineures et correctives rétrocompatibles,
tandis que les changements incompatibles restent hors de votre chemin jusqu’à ce
que vous choisissiez d’adopter une future majeure.

Suivez ce qui a changé dans chaque version dans le
[Journal des modifications](/docs/api/changelog).