Un technicien valide une intervention depuis un entrepôt où le réseau coupe souvent. L’application mobile envoie deux fois la demande, l’API retourne une erreur de validation incompréhensible et le dossier reste pourtant modifié à moitié. Le problème ne se voit pas sur le diagramme, où les endpoints sont propres ; sur le terrain, personne ne sait si la pièce a été consommée.
Le vrai enjeu d’une API interne est de préserver le sens d’une action lorsque le canal, la connexion et le contexte utilisateur varient. Le contrat ne doit pas seulement refléter le backend. Il doit donner aux consommateurs une capacité stable, des erreurs actionnables et une manière sûre de reprendre après une incertitude.
Deux signaux faibles annoncent une API fragile : chaque équipe consommatrice maintient sa propre traduction des statuts, puis le support demande des corrections directes en base pour débloquer les dossiers. Le coût caché se répartit entre frontend, intégrations, tests redondants et diagnostics impossibles à corréler.
Cette méthode relie observation terrain, modèle métier, sécurité, performance et exploitation. Elle aide à construire un premier contrat borné et réversible dans une démarche de développement web sur mesure qui traite l’API comme un produit partagé, pas comme une sortie automatique de la base.
Observer les gestes avant de dessiner les endpoints
Commencez par suivre deux ou trois utilisateurs dans leur environnement réel. Notez l’objectif, les informations consultées, les décisions prises, les interruptions et les contournements. Un écran peut masquer un travail effectué dans un tableur, un appel téléphonique ou une annotation papier indispensable à la décision.
Reconstituez ensuite cinq dossiers : nominal, incomplet, concurrent, repris après interruption et refusé. Pour chacun, identifiez l’état initial, l’action, la règle, le résultat visible et la preuve conservée. Cette matière révèle des capacités métier plus utiles qu’un inventaire de tables.
Interrogez aussi les consommateurs techniques. Le mobile a besoin de travailler avec une connexion intermittente, le portail charge des listes filtrées, le batch rapproche un volume et le support recherche un dossier par plusieurs identifiants. Une même vérité peut exiger des représentations différentes sans dupliquer les règles.
Le livrable n’est pas encore une spécification OpenAPI. C’est une carte des intentions, des données opposables, des délais et des erreurs. Elle permet de refuser les demandes qui exposent un détail interne sans répondre à un geste réel.
Transformer un besoin terrain en promesse d’API
Chaque capacité commence par une phrase vérifiable : « enregistrer une intervention terminée », « réserver une pièce pour un ordre » ou « retrouver les dossiers à contrôler aujourd’hui ». Elle précise l’acteur et le résultat, pas la méthode HTTP. Le contrat technique vient matérialiser cette promesse.
La promesse inclut un délai et un comportement dégradé. Une consultation peut répondre sous une seconde sur le réseau interne ; une commande mobile peut être acceptée localement et synchronisée sous quinze minutes. L’interface doit montrer cette différence au lieu d’afficher un succès définitif avant confirmation.
Elle indique aussi la source de vérité. Si l’ERP possède la consommation de stock, l’API d’intervention ne peut pas inventer une quantité finale. Elle peut accepter l’intention, suivre son état et exposer le refus. Cette frontière évite que les applications discutent ensuite de la donnée « la plus récente ».
Les seuils restent locaux. Un dépassement de trente secondes peut bloquer un contrôle d’accès, tandis qu’un rafraîchissement de référentiel tolère une heure. Chaque seuil déclenche une action : bascule en lecture seule, mise en attente, escalade ou réconciliation.
Exposer des capacités plutôt que des tables
Une API générée directement depuis les entités Doctrine expose les noms, relations et cycles de vie du stockage. Le consommateur doit alors reproduire les règles : modifier trois ressources dans le bon ordre, interpréter les statuts et annuler en cas d’échec. Toute migration de schéma devient une rupture publique.
Une capacité regroupe l’intention dans une transaction cohérente. « Clôturer l’intervention » vérifie les éléments requis, applique les consommations et produit un résultat. Le client ne choisit pas l’ordre des écritures et ne peut pas créer un état que le métier interdit.
Les ressources restent utiles pour consulter une représentation stable : dossier, intervention, équipement. Les commandes explicites couvrent les transitions qui portent une décision. Cette combinaison évite deux excès : une API CRUD sans métier et une prolifération de verbes spécifiques pour chaque bouton.
Contre-intuitivement, une API interne ne doit pas exposer toute la richesse du domaine. Un contrat plus étroit, centré sur les usages prouvés, évolue mieux et limite les données sensibles. Les nouveaux besoins enrichissent la capacité après validation plutôt que de rendre chaque colonne disponible « au cas où ».
Fermer entrées, sorties et erreurs actionnables
L’entrée contient les données choisies par l’acteur, l’identifiant de l’intention et la version de l’état connu. Elle distingue absent, vide et valeur nulle lorsque ces notions ont un sens différent. Les formats de date, montant, unité et identifiant sont explicites et testés sur des exemples réalistes.
La sortie confirme le résultat métier, la version produite et les liens vers la suite utile. Une commande longue retourne un identifiant de suivi et un état ; elle ne garde pas la requête ouverte indéfiniment. Les champs calculés indiquent leur fraîcheur lorsque leur source peut converger plus tard.
Les erreurs possèdent une catégorie stable, un message humain, les champs concernés et une action possible. « Droit insuffisant », « version obsolète », « règle métier refusée » et « dépendance indisponible » ne sont pas interchangeables. Le détail technique reste dans les journaux corrélés, sans exposer la pile au client.
Le contrat définit aussi les répétitions. Une erreur de saisie attend une correction, un conflit demande une relecture et une indisponibilité peut autoriser une nouvelle tentative bornée. Cette sémantique réduit les boucles de retry et permet au frontend d’aider l’utilisateur.
Porter les droits et le contexte sans les disperser
L’authentification identifie l’appelant ; l’autorisation décide s’il peut réaliser cette action sur cette ressource dans ce contexte. Un rôle global « gestionnaire » ne suffit pas si les droits dépendent d’une agence, d’un contrat, d’un état ou d’un montant.
Le backend conserve la décision finale. Le frontend peut masquer un bouton pour l’ergonomie, mais l’API revérifie l’autorisation avec les données opposables. Le refus indique la catégorie et, lorsque c’est acceptable, la condition manquante sans révéler une information sensible.
Les comptes de service reçoivent des permissions limitées à leurs capacités. Un export de reporting ne doit pas pouvoir modifier un dossier. Les jetons ont une durée, une audience et une rotation. Les actions sensibles produisent une trace d’audit avec l’identité humaine lorsque l’appel est réalisé pour son compte.
Cas concret : un responsable régional peut rouvrir une intervention pendant vingt-quatre heures, mais pas modifier la consommation déjà comptabilisée. L’API expose « rouvrir » avec le motif et refuse ensuite la correction de stock, qui suit une capacité distincte et une validation financière.
Concevoir recherche, filtres et pagination utiles
Les usages terrain commencent souvent par une liste : interventions du jour, dossiers en retard, anomalies de mon secteur. L’API doit permettre ces recherches sans obliger le client à télécharger tout le référentiel puis filtrer. Les filtres correspondent aux décisions observées, pas à chaque colonne disponible.
Une pagination par curseur reste stable lorsque de nouveaux éléments arrivent, tandis qu’une pagination par page convient à des ensembles plus statiques. Le tri par défaut et le départage en cas d’égalité sont documentés. Sans ordre stable, un utilisateur peut manquer ou revoir une ligne entre deux appels.
La réponse fournit les champs nécessaires à la liste et un moyen de charger le détail. Multiplier les appels par ligne crée une latence et une charge invisibles lors des tests sur dix dossiers. Mesurez sur la volumétrie du percentile haut et sur le réseau réellement utilisé.
Les exports massifs suivent une capacité asynchrone : demande, suivi, fichier borné et expiration. Une route de liste ne doit pas accepter une limite arbitraire de cent mille éléments. Cette séparation protège la performance du parcours interactif et rend le coût de l’export observable.
Prévoir réseau instable, latence et travail différé
Un terminal mobile peut perdre la connexion après l’envoi mais avant la réponse. L’utilisateur réessaie naturellement. L’application conserve donc un identifiant d’intention et le réutilise, tandis que l’API retourne le résultat déjà produit. Une nouvelle clé créerait un double effet.
Le cache local précise la date et la version des données. Une opération autorisée hors ligne doit pouvoir être validée plus tard ou entrer en conflit. Le produit décide quels gestes restent possibles : saisir un compte rendu peut attendre ; accorder un droit ou engager une somme peut exiger une confirmation en ligne.
Le délai d’expiration et la stratégie de conflit sont visibles. Un technicien ne doit pas découvrir après une heure de saisie que son formulaire ne peut plus être appliqué. Le client sauvegarde un brouillon, signale les champs incompatibles et conserve les données nécessaires à une correction.
Éprouver le contrat dans les conditions du terminal
Testez la latence à 500 millisecondes, la coupure après envoi et la reprise après redémarrage du terminal. Ces chiffres sont des conditions de simulation, pas des objectifs universels. La validation porte sur le résultat, le message utilisateur et l’absence de double consommation.
Par exemple, si plus de 3 % des synchronisations dépassent quinze minutes pendant une tournée, le produit arrête la clôture hors ligne et demande une connexion avant l’engagement suivant. Ce seuil associe un scénario terrain, un impact sur le stock et une décision réversible à valider avec les responsables locaux.
Absorber répétitions et conflits de version
La clé d’idempotence identifie une intention métier pendant une durée définie. L’API persiste la clé, l’empreinte de la demande, le résultat et l’état de traitement. Si la même clé arrive avec un contenu différent, elle refuse le conflit au lieu de choisir silencieusement.
La vérification et l’effet partagent une transaction ou une contrainte unique. Lire « absent » puis écrire ne protège pas contre deux workers concurrents. Pour un effet externe, la clé est transmise au fournisseur lorsqu’il la supporte, et l’état inconnu suit une procédure de vérification.
Le contrôle de version évite l’écrasement. Le client envoie la version lue ; l’API refuse si le dossier a évolué et retourne les éléments nécessaires à l’arbitrage. Une fusion automatique convient à certains champs indépendants, mais pas à une transition de statut ou un montant.
Les répétitions neutralisées et les conflits sont mesurés. Une hausse révèle un problème de réseau, d’interface ou de coordination. L’idempotence protège le métier ; elle ne doit pas cacher indéfiniment un client qui émet deux fois chaque action.
Faire évoluer le contrat sans figer le produit
Une évolution additive — nouveau champ optionnel ou nouvelle valeur explicitement tolérée par les consommateurs — limite la rupture. Le consommateur doit ignorer les champs inconnus lorsqu’il le peut, mais une nouvelle valeur d’énumération exige de vérifier son comportement de repli. Le producteur ne change pas le sens d’un champ existant sous prétexte que son type reste identique.
Les tests de contrat vérifient des exemples partagés et les hypothèses importantes des consommateurs. Ils ne reproduisent pas toute leur logique. L’intégration continue détecte une suppression ou un type incompatible avant le déploiement, puis une phase d’observation confirme les comportements réels.
Une rupture justifiée crée une nouvelle version avec calendrier, guide de migration, mesure d’usage et date de retrait. Le support sait quels clients restent concernés. Maintenir deux versions sans fin augmente chaque correction ; le retrait fait partie du travail, pas d’une dette future anonyme.
Le contrat appartient à une équipe et possède un canal de changement. Une revue avec les consommateurs critiques traite le sens et la transition, pas le style de chaque nom. Les demandes purement locales restent dans le modèle du consommateur plutôt que de gonfler l’API centrale.
Rendre chaque échec compréhensible par le support
Chaque requête reçoit une corrélation rendue au client et propagée aux dépendances, messages et workers. Les journaux structurés indiquent capacité, acteur technique, ressource, version, issue et durée, sans contenir les secrets ni le corps complet par défaut.
Les métriques suivent la latence par capacité, le taux de refus, les erreurs de dépendance, les conflits, les idempotences et les files en attente. Un succès HTTP global masque les refus métier et les traitements différés. Les tableaux sont donc organisés selon les promesses du produit.
Une alerte associe seuil, responsabilité et action : basculer en lecture seule, suspendre une intégration, relancer un worker ou ouvrir une réconciliation. Une notification sans procédure finit par être ignorée. L’exploitation valide les gestes avec des droits proches de la production.
La fiche de mise en œuvre décrit entrées, sorties, dépendances, seuils et journalisation. Une seconde attribue responsabilités, instrumentation et rollback au backend, au consommateur et au run. Deux paragraphes opératoires valent mieux qu’un diagramme exhaustif sans action.
Pour qui cette démarche devient indispensable
Elle concerne les équipes qui partagent une API entre application web, mobile, batch, portail ou partenaires internes. Elle devient prioritaire lorsque les utilisateurs travaillent sur réseau instable, que les droits varient selon le contexte ou que les erreurs créent des interventions support.
Pour un backend utilisé par une seule interface, développé et déployé par la même équipe, un contrat plus simple peut suffire. Les principes d’intention, d’erreurs et de version restent utiles, mais une gouvernance lourde ou un portail dédié n’apporterait pas forcément de valeur.
Le responsable produit de l’API, les développeurs consommateurs, la sécurité, l’exploitation et un représentant terrain participent aux décisions. L’équipe plateforme peut fournir des standards, mais elle ne peut pas deviner les états et compensations du métier.
Erreurs fréquentes des API conçues depuis la base
Exposer chaque entité en lecture et écriture
Cette facilité reporte transactions, droits et règles chez les consommateurs. Conservez les ressources utiles à la consultation et exposez des capacités pour les décisions. Les relations internes n’ont pas à devenir un protocole public.
Retourner une erreur générique pour tous les refus
Le client finit par analyser un texte ou afficher un message inutile. Définissez des catégories, des champs et des actions stables. Un refus attendu fait partie du contrat et doit être testé comme le succès.
Optimiser uniquement le chemin nominal au bureau
Une fibre rapide et dix dossiers masquent les limites du terrain. Simulez latence, coupure, volume et concurrence. La performance se juge sur la décision de l’utilisateur, pas uniquement sur le temps du contrôleur.
Ajouter des champs pour un seul consommateur sans modèle
L’API devient une agrégation de besoins locaux et perd son sens. Vérifiez si l’information appartient à la capacité partagée ou à une projection du consommateur. Une extension justifiée possède une définition et une responsabilité durables.
Matrice de décision pour la première version
Bloc de décision. Incluez les capacités nécessaires à deux parcours complets, leurs refus, la consultation et la reprise. Différez les filtres sans usage prouvé, les agrégations de confort et les opérations dont la source de vérité reste disputée. Refusez toute écriture sans droit, version ni résultat observable.
- D’abord, fermer une intention critique avec son acteur, son état initial et sa preuve finale.
- Ensuite, concevoir le refus, la répétition et le conflit avant d’ajouter une seconde capacité.
- Puis, valider la liste et la latence sur les données et le réseau du terrain.
- Enfin, bloquer l’ouverture si le support ne peut ni corréler un dossier ni appliquer un repli sûr.
Le coût complet comprend développement backend, adaptation des consommateurs, documentation, sécurité, observabilité, assistance et retrait des versions. Une première version plus étroite accélère souvent la valeur parce qu’elle permet d’éprouver ces responsabilités sans multiplier les surfaces.
Plan d’action avec deux consommateurs pilotes
Première semaine : observer et fermer les scénarios
Choisissez une interface web et un mobile ou batch aux contraintes différentes. Suivez deux utilisateurs, reconstituez cinq dossiers et nommez les capacités communes. Documentez la source de vérité, le délai, les erreurs et le mode dégradé de chaque intention.
Produisez un contrat d’exemple avec entrées, sorties, droits, version et corrélation. Faites-le relire par le terrain et le support avant de générer du code. Une question non résolue devient une limite explicite, pas un champ libre ajouté à la demande.
Deuxième semaine : implémenter et provoquer les échecs
Développez une tranche de bout en bout, avec tests de domaine, contrat, adaptateur et journaux. Simulez un doublon, un conflit, une coupure après envoi et une dépendance lente. Le frontend ou le terminal affiche un état fidèle et propose uniquement une action sûre.
Déployez en observation sur un petit groupe. Mesurez performance, refus, répétitions et temps de support. Exécutez le rollback puis confirmez que les intentions engagées restent consultables. Le run enrichit sa procédure à partir des recherches réellement effectuées.
La revue finale relie les responsabilités, l’instrumentation et les seuils aux résultats des deux consommateurs. Elle consigne les dépendances à surveiller et le chemin de repli de chaque capacité. Une divergence non expliquée reste dans le pilote plutôt que d’être masquée par une exception.
Décision de poursuite. Étendez si les deux consommateurs utilisent la même sémantique, si les seuils sont tenus et si le support retrouve un cas sans aide. Différez les capacités dont le sens diverge. Séparez une projection spécifique si elle ne doit pas alourdir le contrat partagé.
Guides complémentaires pour tester et exploiter
Relier les erreurs aux étapes du workflow
Le guide sur les tests de workflows métier et de leurs exceptions aide à vérifier doublons, conflits, délais et reprises avec un verdict utile au produit.
Construire une chronologie exploitable
La méthode d’observabilité des workflows métier complète la corrélation, les seuils et les actions de support autour des appels synchrones et traitements différés.
Ces guides ne remplacent pas l’observation des utilisateurs. Ils transforment les situations terrain en tests et signaux durables, afin que la technique conserve le sens appris pendant le cadrage.
Conclusion : un contrat durable naît des contraintes réelles
Une API interne utile ne se contente pas d’exposer les objets du backend. Elle porte des capacités, des droits, des erreurs et une temporalité que les consommateurs peuvent comprendre sans connaître l’implémentation.
Les usages terrain révèlent les coupures, doublons, conflits et listes qui structurent le vrai contrat. L’idempotence, la version et l’observabilité transforment ces contraintes en comportements testables plutôt qu’en corrections manuelles.
Commencez avec deux consommateurs et une tranche complète. Un périmètre étroit, éprouvé sur des données et réseaux réalistes, construit une base plus durable qu’un catalogue exhaustif d’endpoints sans responsabilité de run.
Pour concevoir ou reprendre cette interface dans votre développement web sur mesure, Dawap peut observer les parcours, fermer le contrat et accompagner un pilote avec le métier, les consommateurs et l’exploitation.
