REST API Design: 10 Principles for Clean APIs — cod-ai.com

Je me souviens encore du jour où j'ai dû expliquer à notre PDG pourquoi notre application mobile consommait les forfaits de données des utilisateurs comme un feu de forêt. C'était en 2016, et j'étais dans mon rôle de Lead API Architect dans une startup fintech depuis trois ans. Notre API REST renvoyait des objets utilisateurs entiers—avec des photos de profil encodées en base64—à chaque fois que l'application vérifiait les soldes de compte. Nous perdions des clients à un rythme alarmant, et c'était moi qui avais conçu l'API qui nous tuait.

Cette leçon douloureuse m'a appris quelque chose de crucial : la conception d'une API REST ne consiste pas seulement à faire fonctionner les choses. Il s'agit de les faire fonctionner bien, à grande échelle, dans des conditions réelles que les manuels scolaires ne mentionnent jamais. Au cours des douze dernières années à construire des APIs pour des entreprises allant de startups de 10 personnes à des entreprises du Fortune 500, j'ai vu les mêmes erreurs répétées d'innombrables fois—et j'en ai commis la plupart moi-même.

Aujourd'hui, je vais partager les dix principes qui ont transformé ma façon de concevoir des APIs. Ce ne sont pas des concepts théoriques tirés d'articles académiques. Ce sont des lignes directrices éprouvées forgées dans des environnements de production servant des millions de requêtes par jour. Que vous construisiez votre première API ou que vous refactorisiez votre dixième, ces principes vous aideront à créer des interfaces que les développeurs souhaitent réellement utiliser.

Principe 1 : Concevez votre API comme un produit, pas comme un wrapper de base de données

La plus grande erreur que je vois dans la conception d'API REST est de traiter l'API comme une fine couche au-dessus des tables de base de données. J'ai examiné des centaines d'APIs où les points de terminaison correspondent un à un aux schémas de base de données, exposant des détails d'implémentation internes qui ne devraient jamais voir le jour. Cette approche crée des interfaces fragiles qui se brisent chaque fois que votre modèle de données évolue.

Lorsque j'ai rejoint ma société actuelle en tant que VP de l'ingénierie de plateforme, notre API avait 47 points de terminaison qui reflétaient directement notre schéma PostgreSQL. Changer le nom d'une seule colonne nécessitait de coordonner des mises à jour à travers 23 applications client différentes. La dette technique asphyxiait notre capacité à innover.

Au lieu de cela, pensez à votre API comme un produit avec son propre cycle de vie, sa stratégie de versionnage et ses considérations d’expérience utilisateur. Les consommateurs de votre API ne se soucient pas de votre stratégie de normalisation de base de données ou de votre architecture de microservices interne. Ils se soucient d'accomplir des tâches spécifiques de manière efficace.

Par exemple, plutôt que d'exposer des points de terminaison séparés pour /users, /user_profiles, /user_preferences, et /user_settings, réfléchissez à ce dont vos consommateurs d'API ont réellement besoin. Dans la plupart des cas, ils veulent un point de terminaison cohérent /users/{id} qui renvoie une ressource soigneusement composée. Utilisez des paramètres de requête comme ?fields=profile,preferences pour permettre aux consommateurs de demander exactement ce dont ils ont besoin.

J'ai implémenté cette approche dans une entreprise SaaS de santé où nous avons réduit notre surface API de 89 points de terminaison à 34 tout en augmentant effectivement la fonctionnalité. Les temps de réponse ont diminué de 43 % car nous avons éliminé le va-et-vient gênant dû à la nécessité d'effectuer plusieurs demandes pour assembler des informations de base. Plus important encore, notre documentation API est devenue compréhensible et le temps d'intégration des développeurs est passé de deux semaines à trois jours.

La clé est de comprendre le modèle de domaine de votre API, qui peut différer considérablement de votre modèle de persistance. Passez du temps avec vos consommateurs d'API—qu'ils soient des équipes frontend internes ou des partenaires externes—et comprenez leurs flux de travail. Concevez les ressources selon leurs modèles mentaux, pas selon vos tables de base de données.

Principe 2 : Adoptez les codes d'état HTTP correctement (mais ne les compliquez pas)

Les codes d'état HTTP sont votre première ligne de communication avec les clients, pourtant je les vois souvent mal utilisés ou complètement ignorés. J'ai un jour audité une API qui renvoyait 200 OK pour chaque réponse, y compris les erreurs, avec le véritable état enfoui dans un champ JSON. Les développeurs pensaient qu'ils étaient utiles en "réussissant toujours", mais ils brisaient en réalité la gestion des erreurs de chaque bibliothèque client HTTP.

Vous n'avez pas besoin de mémoriser tous les 63 codes d'état HTTP, mais vous devez absolument utiliser les principaux correctement. Voici ma répartition pratique basée sur douze ans d'expérience en production :

• 200 OK : GET, PUT ou PATCH réussi qui renvoie du contenu
• 201 Created : POST réussi qui crée une ressource (inclure l'en-tête Location)
• 204 No Content : DELETE ou mise à jour réussie qui ne renvoie rien
• 400 Bad Request : Le client a envoyé des données invalides (inclure des erreurs de validation spécifiques)
• 401 Unauthorized : Authentification requise ou échouée
• 403 Forbidden : Authentifié mais manque de permission
• 404 Not Found : La ressource n'existe pas
• 409 Conflict : La demande entre en conflit avec l'état actuel (création en double, incohérence de version)
• 422 Unprocessable Entity : Syntaxiquement correct mais sémantiquement invalide
• 429 Too Many Requests : Limite de fréquence dépassée (inclure l'en-tête Retry-After)
• 500 Internal Server Error : Quelque chose a planté de votre côté
• 503 Service Unavailable : Panne temporaire ou maintenance

La distinction entre 401 et 403 pose problème à de nombreux développeurs. Pensez à 401 comme "Je ne sais pas qui vous êtes" et à 403 comme "Je sais qui vous êtes, mais vous ne pouvez pas faire ça." Cela a son importance car cela indique aux clients si une nouvelle authentification pourrait aider.

De même, la différence entre 400 et 422 est subtile mais utile. Utilisez 400 pour le JSON malformé ou les champs requis manquants—des éléments qui échouent à l'analyse de base. Utilisez 422 pour les violations de la logique métier comme tenter de transférer plus d'argent que ce qui existe sur un compte. Cette distinction aide les clients à catégoriser les erreurs de manière appropriée.

Dans ma société précédente, nous avons mis en œuvre une utilisation correcte des codes d'état et avons vu nos tickets de support liés aux erreurs API diminuer de 67 % au premier trimestre. Les développeurs pouvaient enfin compter sur la sémantique standard de HTTP au lieu d'analyser les corps de réponse pour déterminer le succès ou l'échec.

Principe 3 : Versionnez votre API dès le premier jour (et faites-le correctement)

J'ai appris cette leçon à mes dépens. En 2014, j'ai lancé une API sans versionnage parce que "nous allons juste maintenir la compatibilité descendante pour toujours." Six mois plus tard, nous avons dû faire un changement critique pour répondre à une exigence commerciale. Nous avions 1 200 consommateurs d'API actifs sans moyen de les migrer progressivement. Le résultat a été une mise à niveau imposée qui a cassé