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. 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.
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.