API Decoupage Administratif du Benin

Le contexte

Tout développeur qui construit une application béninoise finit par avoir besoin du découpage administratif du pays : départements, communes, arrondissements. Formulaires d'adresse, zones de livraison, statistiques territoriales, annuaires locaux — le besoin revient dans presque chaque projet. Or cette donnée, pourtant publique, n'existait pas sous une forme directement exploitable par une application.

Le problème à résoudre

Chacun recréait la liste dans son coin, en la recopiant depuis des documents administratifs souvent au format PDF. Le résultat était prévisible : des orthographes divergentes d'un projet à l'autre, des niveaux hiérarchiques incomplets, et un travail de saisie refait autant de fois qu'il y a de développeurs. Aucune source unique ne faisait référence.

Ce qui a été mis en place

Une API REST publique, développée en PHP avec une base MySQL, qui expose la hiérarchie administrative complète au format JSON. Les niveaux sont interrogeables indépendamment ou en cascade, de façon à alimenter directement des listes déroulantes liées dans un formulaire. Le format de réponse est stable et documenté, pour pouvoir être intégré sans avoir à deviner la structure des données.

Le résultat

Pourquoi une API du découpage administratif manquait au Bénin

Presque toute application qui s'adresse au public béninois a besoin, à un moment, de faire choisir une localisation : un formulaire de livraison, une inscription, une fiche client, un formulaire de contact. Le pays est organisé en départements, communes et arrondissements, et cette hiérarchie est stable. Pourtant, chaque équipe qui développe une application recommence le même travail : trouver les listes, les nettoyer, les saisir en dur dans le code, puis découvrir plus tard qu'il manque une commune ou qu'un nom est mal orthographié.

Ce travail répété a un coût invisible mais réel. Il produit des données de qualité inégale d'une application à l'autre, avec des orthographes divergentes pour la même commune. Quand deux systèmes doivent ensuite échanger des informations, ces écarts deviennent des bogues difficiles à diagnostiquer : la même localité existe sous trois graphies, et aucune correspondance automatique ne fonctionne. C'est le genre de problème qu'on ne voit qu'une fois deux applications mises en relation.

Le second manque est celui de la structure hiérarchique. Une simple liste de communes ne suffit pas : une interface correcte propose d'abord le département, puis filtre les communes correspondantes, puis les arrondissements. Cela suppose que les relations entre niveaux soient explicites et interrogeables, et non déduites d'un fichier plat. C'est exactement ce qu'une API expose naturellement et qu'un fichier CSV recopié ne fournit jamais.

Il y a enfin une dimension d'écosystème. Dans beaucoup de pays, ces données de référence sont publiées par une administration sous forme exploitable. Quand ce n'est pas le cas, chaque développeur bricole dans son coin. Publier une ressource ouverte, documentée et stable fait gagner du temps à tout le monde et améliore la qualité générale des applications locales : c'est un travail d'infrastructure discret, dont la valeur se mesure au nombre de projets qui n'ont plus à le refaire.

Ce type de projet a par ailleurs une vertu pour celui qui le développe : une API publique est visible, testable par n'importe qui, et ne pardonne aucune approximation. Elle constitue une démonstration de rigueur bien plus convaincante qu'une capture d'écran, parce que le lecteur peut la vérifier lui-même en une requête.

Une ressource de ce type gagne enfin à indiquer clairement sa source et sa date de mise à jour. Un développeur qui envisage d'en dépendre veut savoir d'où viennent les données et à quand remonte leur dernière vérification.

Ce qu'on peut en retirer pour concevoir une API

Le premier enseignement est que la constance vaut mieux que l'élégance. Une API dont toutes les réponses ont la même forme, dont les noms de champs suivent la même convention et dont les erreurs se présentent toujours pareil est agréable à consommer, même si aucun choix n'est spectaculaire. À l'inverse, une API brillante mais irrégulière oblige le développeur client à traiter chaque cas séparément.

Le deuxième porte sur la documentation. Une API sans exemples exécutables est une API qu'on n'adopte pas. Deux ou trois requêtes complètes, avec leur réponse réelle, valent mieux qu'une description exhaustive de chaque paramètre. Le développeur qui découvre veut copier-coller une requête et voir un résultat en trente secondes ; s'il n'y parvient pas, il ira chercher ailleurs ou refera le travail lui-même.

Le troisième concerne la stabilité. Une ressource publique crée une dépendance : dès que quelqu'un l'utilise en production, tout changement de format casse son application. Cela impose une discipline, n'ajouter que des champs, ne jamais en renommer, et prévoir un versionnement si une rupture devient inévitable. C'est une contrainte qu'on accepte au moment de publier, pas qu'on découvre après.

Le quatrième, plus général, vaut pour toute entreprise qui expose des données : séparer clairement la donnée de référence de la donnée métier. Les communes d'un pays ne changent presque jamais ; les commandes de vos clients changent en permanence. Mélanger les deux dans la même base et le même code conduit à des migrations pénibles à chaque évolution. Les traiter séparément dès le départ coûte peu et simplifie durablement.

Le dernier point est stratégique plus que technique. Publier une ressource utile et gratuite est une forme de démonstration de compétence bien plus crédible qu'un argumentaire commercial. Un prospect développeur qui utilise votre API se fait une opinion sur votre rigueur en quelques minutes, et cette opinion vaut plus que n'importe quelle page de présentation.

Un aspect souvent sous-estimé est la limitation du débit. Une API publique sans garde-fou finit par être interrogée en boucle par un script mal écrit, ce qui dégrade le service pour tout le monde et alourdit la facture d'hébergement. Une limitation raisonnable par adresse, accompagnée d'un message d'erreur explicite plutôt qu'un silence, protège la ressource sans gêner l'usage normal.

La mise en cache mérite le même soin. Des données de référence qui changent une fois par an n'ont aucune raison d'être recalculées à chaque requête. Des en-têtes de cache corrects permettent aux clients et aux intermédiaires de conserver la réponse, ce qui réduit la charge du serveur et accélère l'expérience côté consommateur, deux bénéfices pour un travail de quelques lignes.

À vérifier avant de publier une API

Ces points déterminent si votre API sera adoptée ou contournée. Ils se tranchent avant la mise en ligne, car chacun devient coûteux à modifier une fois des clients connectés.

• Vos réponses ont-elles toutes la même enveloppe, y compris en cas d'erreur ? Un client ne devrait avoir qu'un seul schéma à traiter.
• Les codes HTTP sont-ils respectés ? Un 200 accompagné d'un message d'erreur oblige chaque client à écrire du code superflu.
• Existe-t-il au moins deux exemples de requêtes copiables-collables, avec leur réponse réelle ?
• Les noms de champs suivent-ils une convention unique ? Mélanger les styles d'écriture dans une même API est le défaut le plus fréquent.
• Les colonnes servant au filtrage sont-elles indexées ? C'est ce qui détermine le temps de réponse quand l'usage augmente.
• Avez-vous prévu comment évoluer sans casser les clients existants ? Ajouter est sûr, renommer ne l'est jamais.
• L'API est-elle joignable en HTTPS, avec des en-têtes CORS corrects ? Sans cela, aucune application web ne pourra l'utiliser depuis un navigateur.
• Qui maintient la donnée quand la réalité change ? Une ressource de référence non tenue à jour devient rapidement pire qu'absente.