Design d'API pour des produits qui continuent d'évoluer

Modéliser le domaine, pas l'écran

Les interfaces changent plus vite que les concepts derrière elles. Une API construite autour d'un écran spécifique tend à exposer l'état de présentation et à forcer des endpoints dupliqués quand de nouveaux clients apparaissent. Partez de ressources de domaine stables, de leur cycle de vie, et des opérations que le métier reconnaît.

Cela n'exige pas une pureté théorique. Une API orientée produit peut agréger des données pour un parcours, mais l'agrégation doit avoir un but et une ownership clairs. Évitez de fuiter directement les tables de base ; la structure de stockage est un détail d'implémentation qui devra finalement changer.

La compatibilité est une fonctionnalité

Les consommateurs déploient à des rythmes différents, surtout les applications mobiles et les intégrations externes. Les changements additifs sont généralement plus sûrs : nouveaux champs optionnels, nouvelles ressources, et nouvelles valeurs d'enum avec des readers tolérants. Retirer ou redéfinir un comportement existant exige un plan de migration, de la télémétrie et une date de fin publiée.

Le versioning est utile quand les sémantiques divergent vraiment, mais les numéros de version ne remplacent pas la discipline de compatibilité. Une API versionnée peut encore surprendre les consommateurs via un ordre changé, un comportement d'erreur, des limites ou l'autorisation. Maintenez un schéma machine-readable et testez des consommateurs représentatifs contre lui.

• Traitez les valeurs d'enum inconnues en sécurité
• Documentez nullabilité et défauts
• Utilisez des tests de contrat pour les consommateurs critiques
• Mesurez l'usage des champs dépréciés avant le retrait

Les mutations ont besoin d'identité

Les retries sont inévitables sur des réseaux peu fiables. Pour les mutations importantes, acceptez une clé d'idempotence scopée au caller et à l'opération. Stockez le résultat pour qu'une requête répétée retourne le résultat original plutôt que de réexécuter l'action.

Le travail long doit retourner une ressource d'opération avec des états explicites. Les clients peuvent poller ou s'abonner sans garder une requête fragile ouverte. Cela améliore aussi le support : le système peut expliquer si le travail est en file, actif, terminé ou échoué — et pourquoi.

L'autorisation appartient au contrat

L'authentification établit l'identité ; l'autorisation décide si cette identité peut effectuer une opération sur une ressource. Appliquez cela côté serveur à la frontière significative la plus étroite. Cacher un bouton côté client est du comportement d'interface, pas du contrôle d'accès.

Les systèmes multi-tenant ont besoin d'un contexte tenant qui ne peut pas être librement fourni et crédité par le client. Dérivez le scope d'une membership vérifiée, validez l'ownership à chaque accès ressource, et journalisez les actions administratives avec assez de contexte pour audit et investigation.

Optimiser pour la compréhension du consommateur

Un naming cohérent, une pagination prévisible, des erreurs utiles, des exemples et un changelog clair réduisent le temps d'intégration plus que des choix de protocole ingénieux. Une API réussit quand les consommateurs peuvent l'utiliser correctement sans apprendre son histoire interne.

Les revues de design doivent inclure les ingénieurs clients et les scénarios opérationnels. L'interface vivra plus longtemps que la première implémentation, donc investissez de la précision sur les parties les plus dures à changer : identifiants, sémantiques, autorisation et cycle de vie.