🔌 La nouvelle API publique
C'est la brique qui rend tout le reste possible. Le site public ne conserve aucune logique métier : il demande des données à l'API et les affiche. Si le contrat est clair et stable, le site reste simple ; s'il est confus, la complexité remonte dans chaque page.
🔌 Ce chantier est porté par Ulrich. Cette page dit ce qui est attendu et pourquoi — pas comment le faire.
Bonne nouvelle : une grande partie existe déjà. La nouvelle API est en construction dans l'ancien dépôt, et les fondations sont solides — versions datées, contrat généré automatiquement, validation systématique des entrées. Ce qui suit distingue ce qui est en place de ce qui reste à faire.
🎯 Ce qu'on attend
Six exigences. Trois sont déjà satisfaites, trois restent à construire.
📜 Le contrat fait foi
déjà làLa description complète de l'API — chaque route, chaque champ, chaque type — est produite automatiquement à partir du code, et servie en ligne.
💡 C'est ce qui permet au site public de générer son client sans recopier quoi que ce soit. Tant que le contrat est juste, le site ne peut pas se tromper sur la forme des données.
📅 Des versions datées, jamais de rupture
déjà làChaque version porte une date. Une application choisit la sienne et continue de fonctionner, même quand une nouvelle sort.
💡 C'est la méthode de Stripe, et elle a fait ses preuves : on peut faire évoluer l'API sans casser les intégrations existantes, et sans négocier une date de migration avec chaque partenaire.
✅ Tout ce qui entre est vérifié
déjà làChaque paramètre reçu est validé avant d'être utilisé. Rien ne traverse l'API sans avoir été contrôlé.
💡 Une API publique reçoit n'importe quoi, volontairement ou non. La validation systématique est la première défense, et elle évite des heures de débogage sur des données malformées.
🔑 Une clé par intégrateur
attenduChaque partenaire reçoit sa propre clé. On peut mesurer son usage, appliquer des limites, et couper son accès sans toucher aux autres.
💡 Sans clés individuelles, on ne sait pas qui appelle quoi, et le jour où un intégrateur pose problème, la seule option est de tout fermer.
🏷️ Chaque donnée porte sa source
attenduUne fiche renvoyée par l'API doit dire quand elle a été mise à jour, par quelle structure, et sous quelle licence elle peut être réutilisée.
💡 C'est notre troisième objectif : les IA ont le droit de lire nos données, à condition de citer la source. Si l'API ne fournit pas cette information, aucune application ne pourra l'afficher, et personne ne pourra nous créditer correctement.
🪶 Simple à utiliser, simple à maintenir
attenduDes noms compréhensibles, des réponses prévisibles, une documentation qu'on peut lire sans connaître le code. Et surtout : le moins de cas particuliers possible.
💡 La complexité d'une API se paie trois fois — quand on l'écrit, à chaque intégration, et à chaque changement. C'est le critère qui doit trancher en cas de doute.
📋 Ce dont le site public a besoin
La liste des usages réels, pour que le contrat parte des besoins plutôt que de ce que la base contient. Chacun correspond à un écran ou à une fonction du site.
| Besoin | Ce que ça suppose |
|---|---|
| 🔍 Chercher des lieux | Par besoin, par endroit, par public accueilli, par horaires. Avec une réponse assez complète pour afficher directement une liste de résultats, sans avoir à rappeler l'API pour chaque lieu. |
| 📄 Afficher une fiche complète | Tout ce que la page d'un lieu montre : horaires détaillés, services, modalités d'accès, publics, transports, contacts, langues parlées, photos, date de mise à jour. |
| 🗺️ Situer les résultats sur une carte | Les coordonnées de chaque lieu, dans la même réponse que la recherche. |
| 🧭 Proposer pendant la frappe | Des suggestions de besoins et de lieux au fur et à mesure de la saisie. C'est souvent le premier contact avec le produit. |
| 🌍 Servir la bonne langue | Le contenu traduit dans les douze langues du produit, en indiquant clairement ce qui est traduit et ce qui ne l'est pas. |
| 🗂️ Lister ce qui existe | De quoi construire les plans du site : la liste des fiches par territoire, avec leur date de dernière modification. |
🗓️ Les étapes, jusqu'à l'extinction de l'ancienne
11 étapes, dont 2 déjà engagées. Chacune porte un critère de sortie : ce qui doit être vrai pour passer à la suivante. Sans cela, une étape reste « bien avancée » pendant des mois.
L'ordre compte autant que la liste. Ouvrir aux intégrateurs avant d'avoir les clés, ou éteindre l'ancienne API avant de savoir qui l'utilise encore, sont deux façons classiques de se créer des ennuis.
1📐 Figer le contrat
en coursDécrire les routes et les données attendues avant d'écrire le code qui les sert. Le contrat part des besoins réels du site public, pas de ce que la base contient aujourd'hui.
✅ On passe à la suite quand : La description de l'API couvre les six besoins du site, et l'équipe qui construira les pages l'a relue.
⚠️ Un contrat écrit après le code décrit ce qu'on a fait, pas ce dont on avait besoin. L'ordre n'est pas un détail.
2🔨 Développement
en coursConstruire les routes, les valider, les tester. Le contrat est produit automatiquement à partir du code, il reste donc toujours juste.
✅ On passe à la suite quand : Toutes les routes du contrat répondent, avec des tests qui couvrent les cas d'erreur autant que les cas nominaux.
3📖 Documentation publique
à fairePublier une documentation lisible sans connaître le code : à quoi sert chaque route, ce qu'elle renvoie, comment gérer les erreurs, avec des exemples qui fonctionnent.
✅ On passe à la suite quand : Quelqu'un d'extérieur réussit un premier appel sans nous poser de question.
⚠️ C'est le test le plus honnête de la simplicité d'une API. Si la documentation doit tout expliquer, c'est que l'API est trop compliquée.
4🔑 Authentification par clés
à faireGénérer une clé par intégrateur, savoir la révoquer, et poser des limites d'usage. Prévoir aussi des clés de test, pour qu'on puisse essayer sans risque.
✅ On passe à la suite quand : Une clé peut être créée, utilisée, limitée et coupée — sans que cela affecte les autres.
⚠️ À faire avant d'ouvrir à qui que ce soit. Ouvrir d'abord et sécuriser ensuite oblige à recontacter tout le monde.
5🧪 Mise en bêta
à faireOuvrir l'API à un petit nombre de personnes de confiance, en annonçant clairement que des choses peuvent encore bouger.
✅ On passe à la suite quand : Deux semaines d'usage réel sans correction bloquante, et les retours des testeurs sont traités.
⚠️ Une bêta où l'on ne casse jamais rien n'est pas une bêta : c'est le moment où corriger coûte encore peu.
6👥 Premiers intégrateurs
à faireAccompagner les premiers partenaires réels, un par un. Regarder ce qu'ils font, ce qu'ils comprennent de travers, ce qui leur manque.
✅ On passe à la suite quand : Trois intégrations tournent en production sans assistance quotidienne de notre part.
⚠️ Ce qu'ils comprennent de travers en dit plus sur l'API que sur eux. C'est la meilleure source d'amélioration qu'on aura.
7📊 Instruments de mesure
à faireSavoir qui appelle quoi, à quelle fréquence, avec quels temps de réponse et quels taux d'erreur. Être prévenu quand quelque chose se dégrade.
✅ On passe à la suite quand : On peut répondre à « qui utilise encore cette route ? » sans ouvrir la base.
⚠️ C'est ce qui rendra possible l'extinction de l'ancienne API. Sans mesure, on coupe à l'aveugle ou on ne coupe jamais.
8🔍 Vérification de compatibilité
à faireComparer systématiquement ce que renvoient l'ancienne et la nouvelle API sur les mêmes demandes, et expliquer chaque écart.
✅ On passe à la suite quand : Tous les écarts constatés sont soit corrigés, soit assumés et documentés.
⚠️ Un chantier de comparaison existe déjà dans l'ancien dépôt. Il ne part donc pas de zéro.
9📣 Annonce et migration
à fairePrévenir tous ceux qui utilisent l'ancienne API, avec une date, un guide de migration, et de l'aide pour ceux qui en ont besoin.
✅ On passe à la suite quand : Chaque intégrateur connu a été prévenu et a répondu, ou a migré.
⚠️ Le préavis doit être large. Certains partenaires ont des cycles de développement longs, et découvrir une coupure la veille les met en difficulté.
10🧊 Gel de l'ancienne API
à fairePlus aucune nouvelle fonctionnalité dessus. On corrige ce qui casse, rien d'autre. Tout ce qui est neuf n'existe que sur la nouvelle.
✅ On passe à la suite quand : Aucun ajout depuis un mois, et les demandes nouvelles arrivent naturellement sur la nouvelle API.
⚠️ Sans gel, l'ancienne API continue de grossir et l'écart avec la nouvelle ne se referme jamais.
11🏁 Extinction
à faireCouper l'ancienne API, après avoir vérifié que le trafic résiduel est nul ou identifié.
✅ On passe à la suite quand : Aucun appel depuis un mois, ou uniquement des appels dont on connaît l'origine et qu'on a acceptés.
⚠️ Couper progressivement — d'abord des coupures courtes et annoncées — révèle les usages oubliés bien mieux qu'une extinction définitive.
🤝 Ce que le site fait de son côté
Le site public ne recopie pas le modèle de données. Il génère son client à partir du contrat publié par l'API, en une commande. Une version est choisie explicitement et n'évolue que sur décision, avec le commit qui va avec.
C'est ce qui permet aux deux équipes d'avancer sans se bloquer : tant que le contrat tient ses promesses, chacun travaille de son côté. Et le jour où l'API évolue, le site le découvre à la compilation — pas en production. 🛡️