Compatibilité ascendante

Cette page est volontairement étroite. Une politique de compatibilité est un engagement public, et un engagement que la plateforme ne tient pas coûte plus cher à un intégrateur que l’absence d’engagement. Ce qui suit est ce que l’API soutient réellement aujourd’hui.

Ce qui est stable

operationId est un contrat public. Chaque opération porte un operationId stable (createWallet, listWithdrawals, rotateWebhookSecret), et ces identifiants deviennent les noms de méthodes dans les SDK générés. En renommer un relève d’une version majeure de SDK, pas d’un changement de routine.

Le préfixe /v2 porte la version. Un changement impossible à faire de façon additive relève d’un nouveau préfixe, pas de celui-ci.

La recette de signature est stable. Elle a changé une fois, avant que l’API n’ait le moindre consommateur ; ce n’est pas quelque chose qui bouge aujourd’hui.

Ce qui peut changer sans préavis, et comment y survivre

Les évolutions sont additives : nouveaux champs dans une réponse, nouvelles valeurs d’énumération, nouveaux endpoints, nouveaux types d’événements webhook.

Votre client doit donc ignorer les champs qu’il ne reconnaît pas, et ne pas s’interrompre sur une valeur d’énumération jamais vue. C’est la seule chose que la plateforme vous demande, et c’est ce qui rend l’évolution additive possible. Si votre analyseur JSON est strict par défaut, assouplissez-le pour les réponses CowriePay. Si vous faites un aiguillage sur une énumération, prévoyez une branche par défaut.

Notez ce que cette phrase est et n’est pas : c’est une consigne aux clients, pas la garantie qu’aucun champ ne sera jamais retiré. Elle est formulée comme un conseil à dessein.

Ce qui n’est PAS encore promis

Être explicite sur les manques est tout l’objet de cette page :

• Il n’existe pas de fenêtre de dépréciation formelle. Pas de délai de préavis publié, pas d’en-tête Sunset, pas de version d’API datée sur laquelle vous figer.
• Il n’est pas garanti qu’un champ ne soit jamais retiré. La surface publiée s’est déjà resserrée : des valeurs de scopes et des types d’événements webhook ont été retirés de la spécification publiée lorsque la fonctionnalité derrière eux n’était pas disponible. Un client qui les aurait inscrits en dur aurait dû changer.
• Les énumérations ne sont pas des ensembles fermés. Traitez-les toutes comme ouvertes.

Si vous avez besoin d’un engagement plus fort pour un achat ou un contrat, demandez-le : c’est une conversation commerciale, pas technique, et elle vaut mieux explicite que déduite d’une page de documentation.