Leçon 10 : Design d'API : Créer des interfaces agréables à utiliser

Une API (Application Programming Interface) est le visage public de votre code, qu'il s'agisse d'un point de terminaison HTTP ou d'une méthode publique au sein d'une classe. La qualité de cette interface détermine le Vibe ressenti par ses consommateurs.

Principe 1 : Points de terminaison prévisibles et intuitifs (API externe)

Les API externes (comme les points de terminaison REST) doivent respecter les conventions standards pour minimiser la charge cognitive des utilisateurs externes.

• Utiliser des noms, pas des verbes, pour les ressources : /users et non /getUsers.
• Utiliser les verbes HTTP pour les actions : GET (récupérer), POST (créer), PUT/PATCH (mettre à jour), DELETE (supprimer).
• Structure de réponse cohérente : Retournez toujours des données, des codes d'état et des formats d'erreur prévisibles (ex : réponse JSON avec des clés d'erreur cohérentes).

Principe 2 : Interfaces internes minimalistes (Vibe DX)

Lors de la conception de l'interface d'une classe ou d'un module, visez la simplicité. Les consommateurs ne devraient pas avoir besoin de connaître les rouages internes complexes pour l'utiliser.

La loi de Déméter (Le vibe « Ne parlez pas aux étrangers »)

Évitez les chaînages de méthodes qui nécessitent de naviguer profondément dans les structures d'objets, car cela couple fortement votre code.

python

Mauvais Vibe : Couplage fort, longue chaîne

user.getAccount().getSubscription().getPlan().name

Bon Vibe : L'objet User abstrait la complexité

user.getSubscriptionPlanName()

Principe 3 : Valeurs par défaut et contraintes sensées

Concevez vos API pour qu'elles acceptent le cas d'utilisation le plus courant avec un effort minimal, en fournissant des valeurs par défaut judicieuses. Si un paramètre est presque toujours « true », faites de « true » la valeur par défaut.