Concevoir des API qui vieillissent bien
Les bonnes API sont discrètes. Elles font exactement ce que l'on attend et continuent de fonctionner longtemps après qu'on a cessé d'y penser. Voici comment concevoir pour ce type de longevité.
Les meilleures API paraissent évidentes après coup. Vous appelez une méthode, elle accomplit l'unique chose que son nom promet, et elle continue de se comporter ainsi à travers une douzaine de versions. Cette fiabilité n'est pas le fruit du hasard. Elle résulte d'une poignée de décisions prises tôt et défendues dans la durée.
Nommez les choses pour l'appelant, pas pour l'implémentation
Une API est une promesse écrite dans des noms de méthodes. Lorsque vous nommez une fonction selon son fonctionnement interne, chaque refactorisation menace de rompre cette promesse. Nommez-la selon ce que veut l'appelant, et l'implémentation reste libre de changer en dessous.
Le test est simple : lisez le site d'appel à voix haute. Si un nouveau coéquipier peut deviner ce qui se passe sans ouvrir le code source, le nom fait son travail.
Rendez le cas courant sans effort
La plupart des appelants veulent la même chose la plupart du temps. Concevez le chemin par défaut pour qu'il ne nécessite aucune configuration, puis superposez des options pour les cas rares. Une API qui exige cinq paramètres pour une tâche de routine sera enveloppée dans une fonction d'assistance par la première équipe qui l'utilise, et vous maintenez désormais deux interfaces au lieu d'une.
Chaque argument obligatoire est une petite taxe que vous prélevez sur chaque appel. Ne la prélevez que lorsque la valeur ne peut réellement pas être déduite.
Versionnez le contrat, pas le code
Les changements incompatibles ne sont pas l'ennemi. C'est la surprise qui l'est. Lorsque vous devez casser quelque chose, donnez-lui un nouveau nom ou une nouvelle version et laissez l'ancien chemin fonctionner pendant une fenêtre de dépréciation claire. Les appelants pardonneront une migration qu'ils peuvent anticiper. Ils ne pardonneront pas un changement silencieux qui casse la production un mardi.
Une API qui vieillit bien est une API à laquelle vous pouvez cesser de penser. Construisez-la de sorte que les personnes qui en dépendent le puissent aussi.