Stabilité du contrat API

Cette page définit la politique de stabilité de l'API publique Pesia dans une version majeure.

Garantie additive-only

Dans une version majeure de l'API (ex. v1), Pesia s'engage à respecter une politique additive-only : seuls des ajouts sont permis, jamais des suppressions ou modifications incompatibles.

Ce qui est GARANTI dans v1

Garantie	Description
Champs requis stables	Aucun champ JSON requis existant ne sera supprimé ou rendu optionnel sans préavis
Endpoints stables	Aucun endpoint existant ne sera retiré sans un runway de ≥ 6 mois
Sémantique stable	Les codes d'erreur, formats de date, types de données existants ne changent pas
Scopes stables	Les scopes actifs existants ne sont pas révoqués ou renommés en v1

Ce qui est PERMIS de façon additive

Ajout permis	Impact sur les intégrations existantes
Nouveaux endpoints	Aucun — ils n'affectent pas les appels existants
Nouveaux champs JSON (optionnels)	Aucun — les parseurs tolérants l'ignorent
Nouveaux scopes	Aucun — les grants existants n'en sont pas affectés
Nouveaux événements webhook	Aucun envoi automatique aux abonnements existants — ajoutez le type souhaité à eventTypes
Nouvelles valeurs d'enum	Aucun (si les parseurs sont tolérants) — recommandé : traiter les valeurs inconnues sans lever d'erreur

Mécanisme Sunset (RFC 8594)

Lorsque Pesia doit déprécier un endpoint ou une version, le mécanisme Sunset est activé :

1. Annonce : émission de l'événement webhook partner_api.version_deprecation avec la date de fin de vie (≥ 6 mois dans le futur).
2. Headers de réponse : chaque réponse de l'endpoint déprécié inclut :
   • Sunset: <HTTP-date> (RFC 8594) — date de retrait
   • X-Pesia-Deprecation: <ISO-8601> — date d'annonce
3. Surveillance recommandée : abonnez-vous à l'événement partner_api.version_deprecation et scannez les headers Sunset dans vos clients HTTP.

Runway minimum de 6 mois

Pesia garantit un minimum de 6 mois entre l'annonce de dépréciation et le retrait effectif d'un endpoint ou d'une version.

Cette garantie permet aux partenaires de :

• Planifier la migration sans urgence
• Tester la nouvelle version en sandbox
• Déployer la migration progressivement

Garanties d'intégration continue

La politique additive-only est vérifiée automatiquement à chaque évolution de l'API :

• Spectral lint : détecte les violations OpenAPI et les patterns non conformes
• oasdiff : compare le spec modifié avec la dernière version stable et bloque les breaking changes (champs requis supprimés, endpoints retirés, types changés)

La vérification CI garantit que les agents et développeurs ne peuvent pas introduire accidentellement un breaking change dans v1 sans passer par le processus de dépréciation avec runway 6 mois.

Recommandations pour les intégrations

Pour construire une intégration robuste :

1. Parseurs tolérants : ignorez les champs JSON inconnus plutôt que de lever une erreur.
2. Valeurs enum inconnues : traitez les nouvelles valeurs d'enum sans exception.
3. Surveillance Sunset : loggez ou alertez sur la présence du header Sunset dans vos réponses.
4. Abonnement webhook : souscrivez à partner_api.version_deprecation pour être notifié des dépréciations (voir Webhooks).

Voir aussi

• Versioning — schéma de versioning, runway, cohabitation v1/v2
• Webhooks — événement partner_api.version_deprecation