Garantie de stabilité de l'API

Quand vous intégrez PermisAPI dans votre produit (logiciel marchand de biens, plateforme PropTech, dashboard interne banque), vous prenez un risque : si on retire un endpoint ou si on casse sa réponse sans préavis, votre intégration tombe en panne et vous devez recoder en urgence.

Ce document fixe nos engagements publics sur :

• Le niveau de stabilité de chaque endpoint (5 niveaux explicites)
• Le préavis minimum avant de retirer un endpoint stable (12 mois)
• Les canaux de notification utilisés pour vous prévenir
• La compatibilité ascendante garantie sur les fonctionnalités stables

C'est un engagement contractuel pour les clients Enterprise, et une promesse publique pour tous les autres plans.

Chaque endpoint de notre API REST et chaque outil MCP (Model Context Protocol) est classé sur l'une des 5 catégories suivantes. Le niveau est indiqué dans la documentation OpenAPI (champ x-stability) et dans la réponse de l'endpoint (header HTTP X-PermisAPI-Stability).

Quand nous devons retirer un endpoint qui était en niveau Stable (par exemple pour cause de migration technique, refonte d'API, dépréciation d'une source de données upstream type Sitadel), nous suivons un processus public en 4 étapes.

1. T0 - Annonce publique de la dépréciation : article dans le changelog public avec la raison, l'endpoint de remplacement recommandé (s'il existe), et la date prévue de retrait. Email envoyé à tous les clients Pro, Business et Enterprise qui ont appelé cet endpoint au moins une fois dans les 90 derniers jours.
2. T0 à T+12 mois - Période de transition : l'endpoint continue de fonctionner exactement comme avant. Un header HTTP Sunset est ajouté à toutes les réponses avec la date de retrait au format RFC 7231. Un header Link pointe vers la documentation de migration.
3. T+9 mois - Rappel 3 mois avant : un nouvel email est envoyé à tous les clients qui continuent d'appeler l'endpoint, avec checklist de migration et l'offre d'une session d'accompagnement gratuite pour les clients Enterprise.
4. T+12 mois - Retrait effectif : l'endpoint passe en HTTP 410 Gone avec une réponse JSON expliquant le statut, l'endpoint de remplacement, et un lien vers la documentation de migration.

Le préavis de 12 mois est un minimum contractuel pour les clients Enterprise et un engagement public pour tous les autres plans. En pratique, certains retraits pourront bénéficier de préavis plus longs (18-24 mois) si la migration est particulièrement complexe.

Les changements suivants ne sont jamais considérés comme des breaking changes et peuvent être livrés à tout moment sans préavis :

• Ajout d'un nouvel endpoint
• Ajout d'un nouveau champ optionnel dans la réponse JSON
• Ajout d'un nouveau paramètre de requête optionnel
• Ajout d'une nouvelle valeur dans un champ enum (avec documentation préalable de votre code défensif)
• Ajout d'un nouvel header de réponse
• Amélioration de la précision d'un champ (par exemple passage d'un score arrondi à un score décimal)
• Amélioration de la fraîcheur ou de la qualité d'une donnée

Les changements suivants sont des breaking changes et déclenchent la politique de retrait avec préavis minimum 12 mois :

• Suppression d'un endpoint
• Suppression ou renommage d'un champ de réponse
• Changement du type d'un champ (int → string par exemple)
• Resserrement d'une validation (par exemple un paramètre qui devient obligatoire alors qu'il était optionnel)
• Changement du comportement d'un endpoint à paramètres identiques
• Changement du format du quota ou des codes d'erreur HTTP

Quatre canaux complémentaires sont utilisés pour l'annonce des dépréciations et retraits :

• Changelog public : https://permisapi.fr/changelog avec un flux RSS à https://permisapi.fr/changelog/feed.xml (Feedly, Inoreader, NetNewsWire compatible).
• Email transactionnel ciblé aux clients qui appellent l'endpoint concerné dans les 90 derniers jours (catégorie transactional = non désabonnable).
• Header HTTP Sunset ajouté automatiquement à chaque réponse pendant toute la période de transition (12 mois minimum). Format RFC 7231 : Sunset: Wed, 11 Mar 2027 23:59:59 GMT.
• Header HTTP Link rel="deprecation" pointant vers la documentation de migration. Format RFC 8288.

L'API actuelle est en version v1 (préfixe d'URL /v1/). Quand une version v2 sera lancée, les deux versions fonctionneront en parallèle pendant au moins 24 mois pour permettre une migration progressive.

Le délai de 24 mois pour les changements de version majeure est supérieur au délai standard de 12 mois pour les retraits d'endpoints individuels, car la migration est plus lourde côté client.

Pour les clients du plan Enterprise (1999 € HT/mois et plus), les engagements de ce document sont opposables et inclus dans le contrat de service. En cas de non-respect :

• Si un endpoint stable est retiré sans le préavis de 12 mois, le client a droit à un crédit équivalent à 1 mois d'abonnement (sur application similaire au mécanisme de crédit SLA, cf page SLA).
• Si un endpoint stable est cassé (breaking change) sans préavis, idem.
• La compensation maximum cumulée sur une année est de 3 mois d'abonnement.

Pour les autres plans (Free, Explorer, Pro, Business), ces engagements sont des promesses publiques non opposables contractuellement, mais nous les respectons dans les faits avec le même niveau de rigueur.

À la date de publication de ce document, voici le récapitulatif des niveaux de stabilité de l'API PermisAPI v1 (la liste complète et à jour est dans la documentation OpenAPI).