Aller au contenu

Informations légales · Cycle de vie de l’API

Garantie de stabilité de l’API

Vos intégrations ne casseront pas du jour au lendemain : nos engagements avant de modifier ou de retirer un point d’accès.

Version 1.2, mise à jour le 13 novembre 2026

1. Pourquoi ce document

Quand vous intégrez PermisAPI dans votre produit (logiciel de marchand de biens, plateforme immobilière, tableau de bord interne d’une banque), vous prenez un risque : si nous retirons un point d’accès ou modifions sa réponse sans préavis, votre intégration tombe en panne et vous devez la corriger en urgence.

Ce document fixe nos engagements publics sur :

  • le niveau de stabilité de chaque point d’accès (5 niveaux explicites) ;
  • le préavis minimum avant de retirer un point d’accès stable (12 mois) ;
  • les canaux utilisés pour vous prévenir ;
  • la compatibilité ascendante garantie sur les fonctionnalités stables.

C’est un engagement contractuel pour les clients de la formule Entreprise, et une promesse publique pour toutes les autres formules.

2. Les 5 niveaux de stabilité

Chaque point d’accès de notre API et chaque outil MCP (Model Context Protocol, utilisé par Claude et ChatGPT) est classé dans l’un des 5 niveaux suivants. Le niveau est indiqué dans la documentation OpenAPI (champ x-stability) et dans la réponse du point d’accès (en-tête HTTP X-PermisAPI-Stability).

Expérimental

Nouveauté en test public. Peut être supprimée ou modifiée sans préavis. Réservée aux premiers utilisateurs qui acceptent l’instabilité en échange d’un accès anticipé. Aucune garantie de continuité : à ne pas utiliser en production critique.

Exemple : un nouveau point d’accès annoncé dans le journal des modifications avec la mention « bêta privée ».

Bêta

Fonctionnalité stabilisée mais encore en validation auprès des utilisateurs. La structure de la réponse peut évoluer (champs ajoutés, renommés) avec un préavis de 30 jours. Adaptée aux intégrations de test et aux usages qui tolèrent le changement.

Exemple : un point d’accès marqué bêta dans la documentation pendant 1 à 2 mois après son lancement.

Stable

Garanti 5 ans au moins. Aucun changement incompatible sans préavis de 12 mois. Les ajouts (nouveaux champs facultatifs, nouveaux points d’accès) sont possibles à tout moment, puisqu’ils ne cassent pas les intégrations existantes. C’est le niveau de la grande majorité des points d’accès de PermisAPI.

Exemple : /v1/permits, /v1/permits/{num_pa}/score, /v1/permits/{num_pa}/parcelle.

Déprécié

Fonctionnalité encore disponible mais annoncée comme prochaine candidate au retrait. Préavis de 6 mois au moins entre la dépréciation et le passage au statut « Retiré ». Pendant cette période, le point d’accès fonctionne exactement comme avant, mais renvoie un en-tête HTTP Sunset avec la date de retrait.

Exemple : un point d’accès /v1/legacy-foo signalé comme déprécié dans le journal des modifications, avec sa date de retrait.

Retiré

Point d’accès définitivement supprimé. Il renvoie HTTP 410 Gone avec un message explicite indiquant le point d’accès de remplacement (s’il existe) et un lien vers la documentation de migration.

Aucun point d’accès n’a été retiré à ce jour. Le premier suivra ce processus complet.

3. Retrait d’un point d’accès stable

Quand nous devons retirer un point d’accès de niveau Stable (par exemple pour une migration technique, une refonte de l’API ou la disparition d’une source de données publique comme Sitadel), nous suivons un processus public en 4 étapes.

  1. Annonce publique de la dépréciation (T0) : article dans le journal des modifications avec la raison, le point d’accès de remplacement recommandé (s’il existe) et la date prévue du retrait. Email envoyé à tous les clients Pro, Business et Entreprise qui ont appelé ce point d’accès au moins une fois dans les 90 derniers jours.
  2. Période de transition (de T0 à T0 + 12 mois) : le point d’accès fonctionne exactement comme avant. Un en-tête HTTP Sunset portant la date du retrait est ajouté à toutes les réponses, et un en-tête Link pointe vers la documentation de migration.
  3. Rappel 3 mois avant (T0 + 9 mois) : un nouvel email est envoyé à tous les clients qui appellent encore le point d’accès, avec une liste des étapes de migration et, pour les clients de la formule Entreprise, une séance d’accompagnement gratuite.
  4. Retrait effectif (T0 + 12 mois) : le point d’accès renvoie HTTP 410 Gone avec une réponse JSON qui explique le statut, indique le point d’accès de remplacement et renvoie vers la documentation de migration.

Le préavis de 12 mois est un minimum contractuel pour les clients de la formule Entreprise et un engagement public pour toutes les autres formules. Certains retraits pourront bénéficier d’un préavis plus long (18 à 24 mois) si la migration est particulièrement complexe.

4. Compatibilité ascendante

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

  • ajout d’un nouveau point d’accès ;
  • ajout d’un nouveau champ facultatif dans la réponse JSON ;
  • ajout d’un nouveau paramètre de requête facultatif ;
  • ajout d’une nouvelle valeur dans un champ à liste de valeurs (votre code doit donc accepter des valeurs inconnues) ;
  • ajout d’un nouvel en-tête de réponse ;
  • amélioration de la précision d’un champ (par exemple, une note arrondie qui devient décimale) ;
  • amélioration de la fraîcheur ou de la qualité d’une donnée.

Les changements suivants sont incompatibles et déclenchent la politique de retrait, avec un préavis de 12 mois au moins :

  • suppression d’un point d’accès ;
  • suppression ou changement de nom d’un champ de la réponse ;
  • changement du type d’un champ (un nombre qui devient du texte, par exemple) ;
  • validation plus stricte (par exemple, un paramètre facultatif qui devient obligatoire) ;
  • changement du comportement d’un point d’accès à paramètres identiques ;
  • changement du format du quota ou des codes d’erreur HTTP.

Exception : la correction d’un défaut, c’est-à-dire d’un comportement qui ne respectait pas la documentation publiée ou les données sources, peut être appliquée sans ce préavis de 12 mois, avec une entrée datée dans le journal des modifications qui dit ce qui a changé. Les changements voulus (nouveau comportement, retrait) restent soumis au préavis.

5. Comment vous serez prévenus

Quatre canaux complémentaires annoncent les dépréciations et les retraits :

  • Le journal des modifications public : permisapi.fr/changelog, avec un flux RSS à l’adresse permisapi.fr/changelog/feed.xml (lisible dans Feedly, Inoreader, NetNewsWire et tout lecteur de flux).
  • Un email envoyé aux clients qui ont appelé le point d’accès concerné dans les 90 derniers jours (email de service, auquel on ne peut pas se désabonner).
  • L’en-tête HTTP Sunset (RFC 8594), ajouté automatiquement à chaque réponse pendant toute la période de transition (12 mois au moins). Exemple : Sunset: Wed, 11 Mar 2027 23:59:59 GMT.
  • L’en-tête HTTP Link rel="deprecation", qui pointe vers la documentation de migration (RFC 8288).

6. Versions majeures de l’API

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

Ce délai de 24 mois pour un changement de version majeure est plus long que le délai de 12 mois prévu pour le retrait d’un point d’accès isolé, car la migration est plus lourde pour vous.

7. Engagement contractuel pour les clients de la formule Entreprise

Pour les clients de la formule Entreprise (sur devis), les engagements de ce document sont opposables et inclus dans le contrat de service. En cas de non-respect :

  • si un point d’accès stable est retiré sans le préavis de 12 mois, le client a droit à un crédit équivalent à 1 mois d’abonnement, appliqué comme les crédits du SLA ;
  • si un point d’accès stable subit un changement incompatible sans préavis, même crédit ;
  • la compensation cumulée sur une année est plafonnée à 3 mois d’abonnement.

Pour les autres formules (Gratuit, Découverte, Explorateur, Régional, Pro, Business), ces engagements sont des promesses publiques, non opposables contractuellement, mais nous les respectons dans les faits avec la même rigueur.

8. Niveau de stabilité actuel des points d’accès

À la date de mise à jour de ce document, voici les niveaux de stabilité de l’API PermisAPI v1 (la liste complète et à jour figure dans la documentation OpenAPI).

NiveauPoints d’accès
StableTous les points d’accès v1 de production, dont :
  • /v1/permits
  • /v1/permits/{num_pa}
  • /v1/permits/near
  • /v1/permits/{num_pa}/score
  • /v1/permits/{num_pa}/parcelle
  • /v1/permits/{num_pa}/risks
  • /v1/permits/{num_pa}/plu
  • /v1/permits/{num_pa}/360
  • /v1/permits/{num_pa}/parcelles-voisines
  • /v1/permits/inside-polygon
  • /v1/score
  • /v1/search
  • /v1/parcelles/{id_parcelle}
  • /v1/stats/*
  • /v1/stats/commune/{code}/density
  • /v1/me/*
  • /v1/billing/*
  • /v1/alerts/*
  • /v1/audit-logs
  • /v1/public/commune-density/*
  • /v1/public/commune-boundary/{code}
BêtaAucun point d’accès en bêta publique actuellement.
ExpérimentalAucun point d’accès expérimental actuellement.
DépréciéAucun point d’accès déprécié actuellement. Un champ l’est : count_by_year (permis de la commune par année de dépôt), servi à l’identique jusqu’au 13 novembre 2027 au moins ; son remplaçant est count_by_year_autorisation.
RetiréAucun point d’accès retiré à ce jour.

9. Historique des versions de ce document

VersionDateÉvolution
1.213 novembre 2026Section 4 : les corrections de défaut peuvent être appliquées sans le préavis de 12 mois, avec une entrée datée dans le journal des modifications.
1.19 octobre 2026Mise en forme. Chemins des points d’accès écrits en entier (par exemple /v1/permits/{num_pa}/plu au lieu de /v1/plu), formule Régional ajoutée à la liste des formules.
1.017 mai 2026Publication initiale.

Vous voulez ces engagements de stabilité par écrit pour votre intégration en formule Entreprise ? Nous signons le contrat cadre sous 48 heures ouvrées.

Demander la signature pour la formule Entreprise

S’abonner aux annonces de dépréciation par RSS : permisapi.fr/changelog/feed.xml