Une API n’est pas une fonctionnalité, c’est un engagement. Le jour où un partenaire branche son système sur la vôtre, chaque champ que vous exposez devient une promesse : le retirer casse son intégration, et cela se paiera en réunions plutôt qu’en code.
D’où une règle qui gouverne tout le reste : n’exposez que ce que vous acceptez de maintenir pendant des années.
Concevoir par les usages, pas par les tables
La tentation est de refléter la base de données : une ressource par table, tous les champs, et que l’appelant se débrouille. Cela produit une API dans laquelle il faut six appels pour afficher un écran, et qui expose la structure interne, donc la fige.
La démarche inverse fonctionne mieux : partir des trois ou quatre choses que les intégrateurs voudront faire, et concevoir les points d’entrée qui les servent en un appel. La structure interne reste libre d’évoluer derrière.
Les décisions à prendre avant le code
1. L’authentification. Qui appelle, comment on le sait, et ce qu’il a le droit de voir. Rétrofiter des permissions fines sur une API déjà ouverte est un chantier douloureux.
2. Les versions. Comment vous publierez un changement incompatible. Le mécanisme doit exister dès la première version, même s’il ne sert pas encore.
3. La pagination. Toute liste qui peut grandir doit être paginée dès le premier jour, y compris celle qui contient douze éléments aujourd’hui.
4. Les erreurs. Un format d’erreur unique, avec un code stable exploitable par du code, et un message lisible par un humain. C’est ce qui détermine si l’intégrateur peut se débrouiller seul ou s’il vous appellera.
5. Les limites d’appel. Un quota annoncé protège votre production et donne à l’intégrateur une contrainte claire. Une limite non annoncée, découverte en incident, ruine la confiance.
La documentation fait partie du produit
Une API sans documentation n’existe pas. Le minimum acceptable : la liste des points d’entrée, un exemple de requête et de réponse pour chacun, les codes d’erreur, et surtout un exemple complet exécutable, de l’authentification au premier résultat utile.
Le meilleur test de qualité tient en une question : un développeur extérieur, sans vous parler, obtient-il un premier appel réussi en moins d’une demi-heure ? Si non, la documentation est incomplète, quel que soit son volume.
Ce qui est surestimé
Le débat sur le style. REST, GraphQL, RPC : le choix compte beaucoup moins que la stabilité du contrat et la qualité des messages d’erreur. Une API REST ennuyeuse et documentée sera toujours préférée à une API élégante dont les réponses changent sans préavis.
Surestimée aussi, la performance brute. Sur presque toutes les intégrations d’entreprise, le facteur limitant n’est pas la milliseconde de réponse mais le nombre d’allers-retours nécessaires pour obtenir une information complète.
Nous écrivons le contrat avant le code, et la documentation avec, dans notre prestation de réalisation d’API.