Abstraction des données selon Barbara Liskov : concevoir des API fiables

Pourquoi Barbara Liskov compte toujours pour la conception d'API

Barbara Liskov est une informaticienne dont les travaux ont discrètement façonné la manière dont les équipes logicielles modernes construisent des systèmes qui ne s'effondrent pas. Ses recherches sur l'abstraction des données, la protection de l'information et, plus tard, le principe de substitution de Liskov (LSP) ont influé sur tout, des langages de programmation à notre façon courante de penser les API : définir un comportement clair, protéger les internals et rendre sûr le fait que d'autres dépendent de votre interface.

« Interfaces fiables » en termes produit

Une API fiable n'est pas juste « correcte » au sens théorique. C'est une interface qui aide un produit à avancer plus vite :

• De nouvelles fonctionnalités sont déployées sans casser les clients existants.
• Les intégrations continuent de fonctionner entre les versions.
• Les incidents en production diminuent parce que les échecs sont prévisibles.
• Les équipes peuvent changer les internals sans une longue coordination.

Cette fiabilité est une expérience : pour le développeur qui appelle votre API, pour l'équipe qui la maintient, et pour les utilisateurs qui en dépendent indirectement.

Comment l'abstraction des données réduit les bugs (et les réunions)

L'abstraction des données consiste à faire interagir les appelants avec un concept (un compte, une file, un abonnement) via un petit ensemble d'opérations — pas via les détails désordonnés de comment c'est stocké ou calculé.

Quand vous cachez les détails de représentation, vous éliminez des catégories entières d'erreurs : plus personne ne peut « par accident » s'appuyer sur un champ de base de données qui n'était pas destiné au public, ni muter un état partagé d'une manière que le système ne supporte pas. Autre point important : l'abstraction réduit le coût de coordination : les équipes n'ont pas besoin d'autorisation pour refactorer les internals tant que le comportement public reste cohérent.

Ce que vous pourrez appliquer après la lecture

À la fin de cet article, vous aurez des façons pratiques de :

• Rédiger des comportements d'API comme des promesses claires (y compris les cas limites).
• Garder les interfaces petites et stables pendant l'évolution des systèmes.
• Concevoir des modes de défaillance prévisibles que les appelants peuvent gérer.

Si vous voulez un résumé rapide plus tard, allez à /blog/a-practical-checklist-for-designing-reliable-apis.

Abstraction des données, expliquée sans jargon

L'abstraction des données est une idée simple : vous interagissez avec quelque chose par ce qu'il fait, pas par la façon dont il est construit.

Pensez à un distributeur automatique. Vous n'avez pas besoin de savoir comment les moteurs tournent ou comment les pièces sont comptées. Il suffit des commandes (« sélectionner un article », « payer », « recevoir l'article ») et des règles (« si vous payez assez, vous obtenez l'article ; si c'est en rupture, vous êtes remboursé »). Voilà l'abstraction.

« Ce que ça fait » vs « comment ça marche »

En logiciel, l'interface est le « ce que ça fait » : noms des opérations, données d'entrée acceptées, sorties produites et erreurs à attendre. L'implémentation est le « comment ça marche » : tables de base, stratégie de cache, classes internes et astuces de performance.

Garder ces deux niveaux séparés permet d'avoir des API stables même quand le système évolue. Vous pouvez réécrire les internals, changer de bibliothèque ou optimiser le stockage — l'interface reste la même pour les utilisateurs.

Types de données abstraits (ADTs) en une minute

Un type de données abstrait est un « conteneur + opérations autorisées + règles », décrit sans s'engager sur une structure interne particulière.

Exemple : une Stack (LIFO).

• push(item) : ajouter un élément
• pop() : retirer et retourner l'élément le plus récemment ajouté
• peek() : regarder l'élément en haut sans le retirer

La clé est la promesse : pop() retourne le dernier push(). Que la pile utilise un tableau, une liste chaînée ou autre chose est privé.

Comment ça se transpose aux API réelles

La même séparation s'applique partout :

• Endpoints REST : POST /payments est l'interface ; contrôles antifraude, retries et écritures en base sont l'implémentation.
• Méthodes d'un SDK : client.upload(file) est l'interface ; découpage en chunks, compression et requêtes parallèles sont l'implémentation.
• Composants UI : un « DatePicker » expose des props/événements ; la structure DOM et la plomberie d'accessibilité sont l'implémentation.

Quand vous concevez avec l'abstraction, vous vous concentrez sur le contrat que les utilisateurs attendent — et vous vous donnez la liberté de changer tout ce qu'il y a derrière sans les casser.

Invariants : les règles cachées qui maintiennent le système correct

Un invariant est une règle qui doit toujours être vraie à l'intérieur d'une abstraction. Si vous concevez une API, les invariants sont les garde-fous qui empêchent vos données de dériver vers des états impossibles — comme un compte bancaire avec deux monnaies à la fois, ou une commande « complétée » sans article.

À quoi ressemblent les invariants (sans maths)

Considérez un invariant comme « la forme de la réalité » pour votre type :

• Un Cart ne peut pas contenir de quantités négatives.
• Un UserEmail est toujours une adresse email valide (pas « validée plus tard »).
• Une Reservation a start < end, et les deux dates sont dans le même fuseau.

Si ces affirmations cessent d'être vraies, votre système devient imprévisible, car chaque fonctionnalité doit deviner ce que signifie une donnée « cassée ».

Comment les invariants guident la validation et le traitement d'erreurs

De bonnes APIs font respecter les invariants aux frontières :

• À la création : rejeter les entrées invalides tôt (retourner une erreur claire).
• Aux mises à jour : n'autoriser que des changements qui maintiennent l'invariant.
• À l'analyse/IO : considérer les données externes comme non fiables ; valider avant stockage.

Cela améliore naturellement le traitement d'erreurs : au lieu d'échecs vagues plus tard (« quelque chose s'est mal passé »), l'API peut expliquer quelle règle a été violée (« end doit être après start »).

Ne laissez pas les invariants fuir via l'interface

Les appelants ne devraient pas avoir à mémoriser des règles internes du type « cette méthode marche seulement après avoir appelé normalize() ». Si un invariant dépend d'un rituel spécial, ce n'est pas un invariant — c'est un piège.

Concevez l'interface pour que :

• les états invalides soient impossibles (ou difficiles à représenter)
• les méthodes préservent automatiquement l'invariant

Checklist pratique pour la documentation

Quand vous documentez un type d'API, notez :

1. Les énoncés d'invariant (anglaise simple, testables)
2. Où ils sont appliqués (constructeur, setters, endpoints)
3. Ce qui arrive en cas de violation (type d'erreur/message, code HTTP)
4. Quelles méthodes les préservent (et exceptions éventuelles)
5. Exemples d'entrées valides vs invalides (brefs, concrets)

Contrats : expliciter le comportement pour les appelants et les mainteneurs

Une bonne API n'est pas juste un ensemble de fonctions — c'est une promesse. Les contrats rendent cette promesse explicite, afin que les appelants puissent se fier au comportement et que les mainteneurs puissent changer l'implémentation sans surprendre personne.

Que préciser dans un contrat

Au minimum, documentez :

• Préconditions : ce qui doit être vrai avant l'appel (plages valides, permissions requises, attentes de thread-safety).
• Postconditions : ce qui sera vrai après un appel réussi (sens de la valeur retournée, changements d'état).
• Effets de bord : ce qui change par ailleurs (écritures sur disque, envoi de requêtes réseau, modification d'objets passés en paramètre).

Cette clarté rend le comportement prévisible : les appelants savent quelles entrées sont sûres et quels résultats gérer, et les tests peuvent vérifier la promesse au lieu d'en deviner l'intention.

Les contrats réduisent la « connaissance tribale »

Sans contrats, les équipes se fient à la mémoire et aux normes informelles : « ne passez pas null ici », « cet appel réessaie parfois », « il renvoie vide en cas d'erreur ». Ces règles se perdent au fil de l'onboarding, des refactors ou des incidents.

Un contrat écrit transforme ces règles cachées en savoir partagé. Il devient aussi une cible stable pour les revues de code : les discussions deviennent « ce changement satisfait-il toujours le contrat ? » au lieu de « chez moi ça marchait ».

Formulations bonnes vs vagues (exemples)

Vague : « Crée un utilisateur. »

Mieux : « Crée un utilisateur avec un email unique.

• Préconditions : email doit être une adresse valide ; l'appelant doit avoir la permission users:create.
• Postconditions : retourne le nouveau userId ; l'utilisateur est persisté et immédiatement récupérable.
• Modes d'échec : retourne 409 si l'email existe déjà ; retourne 400 pour champs invalides ; aucun utilisateur partiel n'est créé. »

Vague : « Récupère des éléments rapidement. »

Mieux : « Retourne jusqu'à limit éléments triés par createdAt décroissant.

• Effets de bord : aucun.
• Cohérence : peut être obsolète jusqu'à 60 secondes.
• Pagination : utilisez nextCursor pour la page suivante ; les cursors expirent après 15 minutes. »

Information hiding : garder les internals privés, garder les APIs stables

L'information hiding est l'aspect pratique de l'abstraction des données : les appelants doivent dépendre de ce que l'API fait, pas de comment elle le fait. Si les utilisateurs ne voient pas vos internals, vous pouvez les changer sans transformer chaque release en un breaking change.

Exposez des opérations, pas la représentation

Une bonne interface publie un petit ensemble d'opérations (create, fetch, update, list, validate) et garde la représentation — tables, caches, files, limites de service — privée.

Par exemple, « ajouter un article au panier » est une opération. « CartRowId » de votre base est un détail d'implémentation. Quand vous exposez ce détail, vous invitez les utilisateurs à construire leur logique dessus, ce qui fige votre capacité à changer.

Pourquoi cacher les internals rend les refactors sûrs

Quand les clients ne dépendent que d'un comportement stable, vous pouvez :

• changer de base de données ou de format de stockage
• découper un monolithe en services
• ajouter du caching ou modifier les index
• réorganiser les modèles internes

…et l'API reste compatible parce que le contrat n'a pas bougé. C'est le vrai avantage : stabilité pour les utilisateurs, liberté pour les mainteneurs.

Schémas courants de fuite d'internals à surveiller

Quelques façons dont les internals s'échappent accidentellement :

• Retourner des IDs internes qui n'ont de sens que dans votre couche de stockage (entiers auto-incrémentés, clés de shard).
• Exposer des structures mutables (p.ex. retourner un objet brut que les clients peuvent modifier et renvoyer), ce qui couple les clients à vos champs exacts.
• Permettre aux clients de construire l'état interne, comme accepter status=3 au lieu d'un nom clair ou d'une opération dédiée.

Concevoir des formes de réponse stables

Préférez des réponses qui décrivent le sens, pas le mécanisme :

• Utilisez des identifiants publics opaques et stables (ex. "userId": "usr_...") plutôt que des numéros de ligne en base.
• Retournez des copies ou des vues en lecture seule de collections plutôt que des structures dont l'ordre ou les champs internes sont « accidentellement » utilisés.
• Ajoutez des champs de façon rétrocompatible ; évitez de changer le sens des champs existants.

Si un détail peut changer, ne le publiez pas. Si les utilisateurs en ont besoin, promouvez-le en tant que partie délibérée et documentée de la promesse d'interface.

Le principe de substitution de Liskov comme promesse d'interface

Le Principe de Substitution de Liskov (LSP) en une phrase : si un morceau de code fonctionne avec une interface, il doit continuer à fonctionner quand vous y substituez n'importe quelle implémentation valide de cette interface — sans cas spéciaux.

LSP parle moins d'héritage et plus de confiance. Quand vous publiez une interface, vous faites une promesse sur le comportement. LSP dit que chaque implémentation doit tenir cette promesse, même si elle utilise une approche interne très différente.

LSP = « ne surprenez pas l'appelant »

Les appelants se fient à ce que votre API dit — pas à ce qu'elle fait actuellement. Si une interface dit « vous pouvez appeler save() avec n'importe quel enregistrement valide », alors chaque implémentation doit accepter ces enregistrements valides. Si une interface dit « get() retourne une valeur ou un résultat clair ‘not found’ », alors les implémentations ne peuvent pas lancer des erreurs aléatoires ou retourner des données partielles.

Une extension sûre signifie que vous pouvez ajouter de nouvelles implémentations (ou changer de fournisseur) sans forcer les utilisateurs à réécrire leur code. C'est le bénéfice pratique du LSP : garder les interfaces remplaçables.

Violations courantes du LSP dans les API

Deux façons communes de rompre la promesse :

• Entrées plus restreintes (préconditions plus strictes) : une nouvelle implémentation rejette des entrées que la définition de l'interface autorisait. Exemple : l'interface accepte toute chaîne UTF‑8 comme ID, mais une implémentation n'accepte que des IDs numériques.

• Sorties affaiblies (postconditions moins fortes) : une implémentation retourne moins que promis. Exemple : l'interface dit que les résultats sont triés, uniques ou complets — et une implémentation renvoie des données non triées, des doublons ou en supprime silencieusement.

Violation subtile : changer le comportement d'échec — si une implémentation renvoie « non trouvé » et qu'une autre lance une exception pour la même situation, les appelants ne peuvent pas substituer l'une à l'autre en toute sécurité.

Concevoir un comportement plug-in sans surprises

Pour supporter des « plug-ins », rédigez l'interface comme un contrat :

• Spécifiez quelles entrées sont valides et conservez cet ensemble cohérent entre les implémentations.
• Spécifiez ce que signifient les sorties (ordre, valeurs par défaut, cas limites).
• Standardisez les modes d'échec : quelles erreurs peuvent survenir et ce qu'elles représentent.

Si une implémentation nécessite vraiment des règles plus strictes, ne les cachez pas derrière la même interface. Soit (1) définissez une interface séparée, soit (2) faites de la contrainte une capacité explicite (par ex. supportsNumericIds() ou une configuration documentée). Ainsi, les clients s'engagent en connaissance de cause plutôt que d'être surpris par une « substitution » qui n'est pas réellement substituable.

De bonnes interfaces sont petites, cohésives et lisibles

Une interface bien conçue paraît « évidente » à utiliser car elle expose seulement ce dont l'appelant a besoin — et pas plus. La vision de Liskov sur l'abstraction des données vous pousse vers des interfaces étroites, stables et lisibles, pour que les utilisateurs puissent s'y fier sans connaître les détails internes.

Préférez cohésion plutôt que « tout-faire »

Les grosses APIs mélangent souvent des responsabilités sans lien : configuration, changements d'état, reporting et troubleshooting au même endroit. Cela rend difficile de comprendre ce qu'il est sûr d'appeler et quand.

Une interface cohésive regroupe des opérations appartenant à la même abstraction. Si votre API représente une file, concentrez-vous sur les comportements de file (enqueue/dequeue/peek/size), pas sur des utilitaires généraux. Moins de concepts signifie moins de voies d'utilisation incorrecte.

Évitez des paramètres trop flexibles qui créent de l'ambiguïté

« Flexible » veut souvent dire « flou ». Des paramètres comme options: any, mode: string ou plusieurs booléens (par ex. force, skipCache, silent) créent des combinaisons mal définies.

Privilégiez :

• des méthodes spécifiques pour des comportements distincts (ex. publish() vs publishDraft()), ou
• un petit objet d'options bien typé avec des valeurs par défaut documentées et des combinaisons invalides interdites.

Si un paramètre oblige les appelants à lire la source pour savoir ce qui arrive, ce n'est pas une bonne abstraction.

Le nommage fait partie de l'interface

Les noms communiquent le contrat. Choisissez des verbes qui décrivent un comportement observable : reserve, release, validate, list, get. Évitez les métaphores cryptiques et les termes surchargés. Si deux méthodes semblent similaires, les appelants supposeront qu'elles se comportent de manière similaire — faites en sorte que ce soit vrai.

Quand scinder en modules/ressources

Séparez une API quand vous remarquez :

• des rôles utilisateurs différents (ex. « admin » vs « consumer ») ayant des capacités distinctes, ou
• des rythmes d'évolution différents (une partie évolue fréquemment, une autre doit rester stable).

Des modules séparés vous permettent d'évoluer les internals tout en gardant la promesse centrale. Si vous prévoyez de la croissance, envisagez un « core » mince plus des extensions ; voir aussi /blog/evolving-apis-without-breaking-users.

Faire évoluer les API sans casser les utilisateurs

Les API évoluent rarement peu. De nouvelles fonctionnalités arrivent, des cas limites sont découverts, et des « petites améliorations » peuvent silencieusement casser des applications réelles. Le but n'est pas de geler une interface, mais de l'évoluer sans violer les promesses dont les utilisateurs dépendent déjà.

Versioning sémantique (pratique, avec limites)

Le versioning sémantique est un outil de communication :

• MAJOR : changement cassant.
• MINOR : ajout de fonctionnalité rétrocompatible.
• PATCH : correction de bug sans changer le comportement prévu.

Limite : il faut aussi du jugement. Si une « correction » change un comportement sur lequel des appelants comptaient, c'est un breaking change en pratique — même si l'ancien comportement était accidentel.

Les breaking changes concernent les contrats, pas seulement les types

Beaucoup de breaking changes n'apparaissent pas au compilateur :

• Resserrement des règles d'entrée (rejeter des valeurs qu'on acceptait avant).
• Changement de sens (mêmes champs, interprétation différente).
• Changement de temporalité (un appel rapide devient lent ou bloquant).
• Changement du comportement d'erreur (nouveaux codes, retries différents, résultats partiels différents).

Pensez en termes de préconditions et postconditions : ce que les appelants doivent fournir et ce qu'ils peuvent compter recevoir.

Chemins de dépréciation suivables par les utilisateurs

La dépréciation fonctionne quand elle est explicite et datée :

• Marquez le comportement ancien comme déprécié dans la doc et les réponses (warnings, en-têtes, logs).
• Offrez une fenêtre de double support (ancien et nouveau côte à côte).
• Publiez un calendrier clair (ex. « nouveau par défaut dans 60 jours, retrait dans 180 jours »).

Comment l'abstraction facilite l'évolution

L'abstraction de type Liskov aide parce qu'elle restreint ce que les utilisateurs peuvent exploiter. Si les appelants se contentent du contrat — pas de la structure interne — vous pouvez changer formats de stockage, algorithmes et optimisations librement.

Concrètement, de bons outils aident aussi. Par exemple, si vous itérez vite sur une API interne pour une app React ou un backend Go + PostgreSQL, un workflow d'accélération comme Koder.ai peut accélérer l'implémentation sans changer la discipline centrale : vous voulez toujours des contrats nets, des identifiants stables et une évolution rétrocompatible. La vitesse est un multiplicateur — autant multiplier les bonnes habitudes d'interface.

Gestion des erreurs et modes de défaillance : concevoir pour la prévisibilité

Une API fiable n'est pas celle qui ne tombe jamais en panne, mais celle qui échoue de manière compréhensible, gérable et testable. La gestion des erreurs fait partie de l'abstraction : elle définit ce que signifie « usage correct » et ce qui arrive quand le monde (réseau, disque, permissions, temps) n'est pas d'accord.

Erreurs de programmeur vs défaillances runtime

Commencez par séparer deux catégories :

• Erreurs de programmeur : l'appelant a violé le contrat (format d'ID invalide, appels hors séquence, champs manquants). Elles doivent être détectées tôt et bruyamment — souvent par des erreurs de validation qui pointent directement l'abus.
• Défaillances runtime : l'appelant a respecté le contrat, mais quelque chose d'externe a échoué (timeouts, dépendances indisponibles, limites de quota, conflits de concurrence). Elles doivent être représentables et récupérables.

Cette distinction garde l'interface honnête : les appelants savent ce qu'ils peuvent corriger dans le code vs ce qu'ils doivent gérer à l'exécution.

Utilisez le contrat pour choisir la bonne forme d'échec

Votre contrat doit impliquer le mécanisme :

• Erreurs (réponses de validation) pour les violations de contrat.
• Exceptions pour des échecs vraiment exceptionnels, dans des bibliothèques — ou quand vous ne pouvez pas raisonnablement forcer chaque site d'appel à gérer les branches.
• Types résultat (ex. Ok | Error) quand les échecs sont attendus et que vous voulez que les appelants les gèrent explicitement.

Peu importe le choix, soyez cohérent sur toute l'API pour que les utilisateurs n'aient pas à deviner.

Rendre les modes de défaillance explicites et testables

Listez les échecs possibles par opération en termes de sens, pas de détails d'implémentation : « conflit dû à une version obsolète », « non trouvé », « permission refusée », « rate limited ». Fournissez des codes d'erreur stables et des champs structurés pour que les tests puissent affirmer le comportement sans matcher des chaînes.

Reprises, idempotence et succès partiel

Documentez si une opération est sûre à retenter, dans quelles conditions, et comment obtenir l'idempotence (clés d'idempotence, IDs de requête naturels). Si un succès partiel est possible (opérations en lot), définissez comment succès et échecs sont rapportés, et quel état les appelants doivent supposer après un timeout.

Tester les abstractions : prouver que l'interface tient sa promesse

Une abstraction est une promesse : « Si vous appelez ces opérations avec des entrées valides, vous obtiendrez ces résultats, et ces règles tiendront toujours. » Les tests sont le moyen de tenir cette promesse au fil des changements.

Transformez les contrats en tests unitaires et d'intégration

Commencez par traduire le contrat en vérifications automatisables.

Les tests unitaires doivent vérifier les postconditions et les cas limites de chaque opération : valeurs retournées, changements d'état et comportement en erreur. Si votre interface dit « supprimer un élément non existant renvoie false et ne change rien », écrivez exactement ça.

Les tests d'intégration doivent valider le contrat au travers des frontières réelles : base de données, réseau, sérialisation et auth. Beaucoup de « violations de contrat » n'apparaissent qu'au moment de coder/decoder les types ou quand les retries/timeouts interviennent.

Tests basés sur les propriétés pour les invariants

Les invariants sont des règles qui doivent rester vraies pour n'importe quelle séquence d'opérations valides (ex. « le solde ne devient jamais négatif », « les IDs sont uniques », « les éléments retournés par list() peuvent être récupérés par get(id) »).

Le property-based testing vérifie ces règles en générant beaucoup d'entrées valides et de séquences d'opérations aléatoires, cherchant des contre-exemples. Conceptuellement, vous dites : « Peu importe l'ordre des appels, l'invariant tient. » C'est excellent pour trouver des cas limites étranges que les humains n'ont pas envisagés.

Contract testing piloté par les consommateurs pour les APIs publiques

Pour les APIs publiques ou partagées, laissez les consommateurs publier des exemples de requêtes qu'ils effectuent et des réponses sur lesquelles ils comptent. Les fournisseurs exécutent ensuite ces contrats en CI pour confirmer que les changements ne cassent pas des usages réels — même quand l'équipe fournisseur ne connaissait pas ces usages.

Surveiller la production pour la dérive du contrat

Les tests ne couvrent pas tout, donc surveillez des signaux qui suggèrent que le contrat change : modifications de la forme de réponse, augmentation des taux 4xx/5xx, nouveaux codes d'erreur, pics de latence et échecs de désérialisation « champ inconnu ». Surveillez par endpoint et par version pour détecter la dérive tôt et réagir.

Si vous supportez des snapshots ou des rollback dans votre pipeline de livraison, ils se combinent naturellement avec cet état d'esprit : détecter la dérive tôt, puis revenir en arrière sans forcer les clients à s'adapter en pleine urgence. (Koder.ai, par exemple, inclut snapshots et rollback dans son workflow, ce qui s'aligne bien avec l'approche « contrats d'abord, changements ensuite ».)

Anti-patterns courants et comment les éviter

Même les équipes qui valorisent l'abstraction tombent dans des pratiques qui semblent « pratiques » sur le moment mais transforment progressivement une API en un ensemble de cas particuliers. Voici quelques pièges récurrents — et quoi faire à la place.

Feature flags permanents comme réglages d'API

Les feature flags sont utiles pour le déploiement, mais le problème arrive quand les flags deviennent des paramètres publics et long-terme : ?useNewPricing=true, mode=legacy, v2=true. Avec le temps, les appelants les combinent de manières imprévues et vous vous retrouvez à supporter plusieurs comportements indéfiniment.

Approche plus sûre :

• Gardez les flags de rollout internes quand c'est possible.
• Si le comportement doit différer, exprimez-le comme une nouvelle capacité avec un nom clair et un cycle de vie (et un plan pour supprimer l'ancien).
• Documentez quelles combinaisons sont valides ; rejetez explicitement les autres.

Laisser fuiter des concepts de base de données dans l'interface

Les APIs qui exposent des IDs de table, des clés de jointure ou des filtres « en forme de SQL » (ex. where=...) obligent les clients à apprendre votre modèle de stockage. Un changement de schéma devient alors un changement d'API cassant.

Modélisez plutôt l'interface autour des concepts métier et des identifiants stables. Laissez les clients demander ce qu'ils veulent dire (« commandes pour un client sur une plage de dates »), pas comment vous le stockez.

Le réflexe « ajouter un champ »

Ajouter un champ semble inoffensif, mais des ajouts répétés peuvent brouiller les responsabilités et affaiblir les invariants. Les clients commencent à dépendre de détails accidentels et le type devient une collection fourre-tout.

Évitez le coût à long terme en :

• Introduisant un nouveau type ciblé pour un nouveau concept.
• Groupant les champs liés dans un objet imbriqué au sens clair.
• Traitant chaque ajout comme un changement de contrat : que signifie-t-il et qu'est-ce qui doit rester vrai ?

Quand l'abstraction devient trop stricte

Trop d'abstraction peut bloquer des besoins réels — pagination qui ne peut pas exprimer « commencer après ce curseur », ou endpoint de recherche qui ne peut pas faire une « correspondance exacte ». Les clients contournent alors l'API (appels multiples, filtrage local), causant pire performance et plus d'erreurs.

La solution : flexibilité contrôlée : fournissez un petit ensemble de points d'extension bien définis (par ex. opérateurs de filtre supportés), plutôt qu'une échappatoire ouverte.

Simplifier sans retirer la capacité

La simplification n'implique pas de retirer du pouvoir. Dépréciez des options confuses, mais conservez la capacité sous une forme plus claire : remplacez des paramètres qui se recoupent par un objet de requête structuré, ou scindez un endpoint « tout faire » en deux endpoints cohésifs. Puis accompagnez la migration par une doc versionnée et un calendrier de dépréciation (voir /blog/evolving-apis-without-breaking-users).

Checklist pratique pour concevoir des API fiables

Vous pouvez appliquer les idées d'abstraction de Liskov avec une checklist simple et répétable. Le but n'est pas la perfection — c'est rendre les promesses de l'API explicites, testables et sûres à faire évoluer.

Checklist courte

• Invariants : Quelles règles doivent toujours être vraies sur la ressource ? (ex. « le solde ne devient jamais négatif », « les IDs sont uniques », « les éléments sont retournés dans un ordre stable »).
• Contrats : Pour chaque opération, rédigez préconditions, postconditions et effets de bord (y compris ce qui n'est pas modifié).
• Représentation cachée : Listez les détails intentionnellement privés (format de stockage, caching, IDs internes) et assurez-vous que les appelants ne peuvent pas s'y appuyer.
• Plan d'évolution : Décidez comment ajouter des capacités : stratégie de versioning, politique de dépréciation et durée de support des anciens comportements.

Workflow rapide de revue d'API (répétable)

1. Lire l'interface uniquement (pas l'implémentation). Un nouveau venu peut-il prédire le comportement ?
2. Parcourir 5 « tests histoire » : un cas normal, un cas vide, un cas limite, un cas d'entrée invalide et un cas d'échec.
3. Vérifier la sécurité de substitution : s'il y a plusieurs implémentations, en remplacer une par une autre surprendrait-il les appelants ?
4. Scanner le couplage caché : les clients doivent-ils connaître des états internes, la temporalité ou des détails de stockage ?
5. Écrire les breaking changes que vous êtes sur le point d'introduire, puis repenser jusqu'à ce que la liste soit vide (ou consciemment acceptée).

Modèles de documentation (copier/coller)

Utilisez des blocs courts et cohérents :

• Opération : transfer(from, to, amount)
• Exige : amount > 0 et les comptes existent
• Assure : balances mises à jour atomiquement ; somme totale préservée
• Erreurs : InsufficientFunds, AccountNotFound, Timeout
• Notes : idempotence, ordering, attentes de performance

Lectures complémentaires optionnelles

Pour aller plus loin, cherchez : Abstract Data Types (ADTs), Design by Contract, et le Principe de Substitution de Liskov (LSP).

Si votre équipe garde des notes internes, placez-les depuis une page comme /docs/api-guidelines pour que le workflow de revue reste facile à réutiliser — et si vous construisez de nouveaux services rapidement (manuellement ou avec un assistant de build comme Koder.ai), traitez ces lignes directrices comme non négociables. Les interfaces fiables sont la façon dont la rapidité se capitalise au lieu de se retourner contre vous.