Ressource co-construite avec next-level.run(), les programmes Engineering avancés de Stan Amsellem. Rédigée par Johann Pardanaud, expert en APIs et ex Tech Lead chez Batch. 8 concepts pour maîtriser le design d'API de bout en bout : définition, approche produit, idempotency, authentification, pagination, versioning, monitoring et HATEOAS.
1. Les bases à maîtriser
API signifie Application Programming Interface. C'est un ensemble d'actions mises à disposition par une application pour permettre à d'autres applications d'interagir avec elle. Chaque action répond à un besoin concret et s'articule autour de verbes : lire, poster, mettre à jour.
Exemple concret : Une application de vente en ligne veut envoyer une notification Slack à chaque nouvelle commande. Slack expose une API avec des actions comme 'poster un message dans un channel'. L'application appelle cette API pour exécuter l'action automatiquement.
Bonne pratique : Commencer par identifier les actions que l'API doit exposer. Ces actions doivent répondre à des besoins concrets. Ne pas complexifier avec des actions inutiles ou redondantes.
Conseil : Se poser la question : 'Quelles sont les actions nécessaires pour résoudre le problème de mes utilisateurs ?'. Moins d'endpoints = meilleure maintenabilité.
2. Votre API est un produit, pas un simple outil technique
Une API n'est pas qu'un sujet technique à déléguer aux développeurs. C'est un produit à part entière qui participe à la stratégie business. Les équipes produit doivent être impliquées dans son évolution.
Exemple concret : Stripe et Mangopay ont leur API au coeur de leur business model. Elle est documentée, facile à utiliser, et alignée avec les besoins des utilisateurs. Leurs équipes produit traitent l'API comme un atout business.
Vigilance : Si l'équipe produit n'est pas impliquée dans l'évolution de l'API, le design risque de ne pas correspondre aux usages réels. Le naming des actions doit être en phase avec le jargon produit. Si l'app parle de 'photos' et l'API utilise 'images', il y a un problème d'alignement.
Bonne pratique : Organiser des sessions de design API avec l'équipe produit pour aligner l'API avec l'expérience utilisateur. Cela améliore l'adoption par les clients.
Conseil : Documenter tout. Prendre exemple sur Stripe : documentation fluide, complète, avec des exemples concrets et accessible à tous les niveaux. Une bonne documentation réduit les questions répétitives et améliore l'adoption.
3. Éviter les doublons dans les requêtes API
L'idempotency est la capacité d'une API à produire le même résultat même si une requête est envoyée plusieurs fois. Concept critique mais souvent négligé dans le design des APIs.
Exemple concret : Une API qui crée des commandes. Un utilisateur clique deux fois sur 'Payer' à cause d'un problème de connexion. Sans idempotency : deux commandes créées. Avec idempotency : une seule commande, grâce à une idempotency key qui garantit l'unicité du traitement.
Sans idempotency : La première requête est envoyée, la réponse n'est pas reçue à cause d'une erreur réseau. On rejoue la requête. Résultat : deux commandes créées.
Avec idempotency : La key garantit que la requête sera idempotente. La commande est créée une première fois. Les requêtes suivantes retournent toujours la même commande.
Bonne pratique : Implémenter des idempotency keys pour les actions critiques : création de commandes, paiements. Cela évite les doublons et les erreurs imprévues.
Conseil : Pour chaque action API, se demander : 'Cette action doit-elle être idempotente ?'. Les actions GET sont naturellement idempotentes. Les actions POST et PUT ne le sont pas toujours. Identifier celles qui doivent l'être dès le départ.
4. Fonctionnement et limites
Le JWT (JSON Web Token) est un standard pour transmettre des informations de manière sécurisée entre deux systèmes. Utilisé principalement pour l'authentification, il garantit qu'un ensemble de données a été émis par un tiers de confiance, sans possibilité de falsification.
Structure du JWT Un JWT est composé de trois parties : Header (type de token et algorithme de signature), Payload (données à transmettre, signées mais non chiffrées), Signature (empreinte unique générée à partir du header, du payload et d'une clé secrète).
Avantages : Stateless (pas besoin de base de données pour vérifier l'authentification), Sécurisé (les JWT sont signés, ce qui assure l'intégrité des données), Interopérable (standardisé, utilisable pour différents cas).
Inconvénients : Token non révocable (reste valide jusqu'à expiration même après déconnexion), Modification des accès (un changement de droits n'invalide pas le token actuel).
Vigilance : Éviter d'utiliser le JWT pour gérer des sessions utilisateur. L'impossibilité de révoquer un token le rend peu adapté. Préférer des sessions stockées côté serveur dans une base Key-Value (Redis).
Bonne pratique : Utiliser des algorithmes sécurisés (HMAC, RSA) pour signer les tokens. Spécifier explicitement l'algorithme attendu pour éviter l'exploitation d'un algorithme faible.
Conseil : Préférer le JWT pour des échanges sécurisés entre systèmes (webhooks) plutôt que pour la gestion de sessions. Opter pour une librairie réputée (Auth0) et la maintenir à jour.
5. Performance et bonnes pratiques
La pagination est critique pour la performance d'une API, surtout avec de grandes bases de données. Tout le monde la connaît, mais peu savent bien l'implémenter.
Exemple concret : La pagination par offset est simple et répandue. Pour afficher la page 2, on saute les 10 premières lignes. Mais si les données changent fréquemment, les résultats se décalent : doublons ou éléments manquants.
Vigilance : L'offset SQL peut être très lent sur des bases volumineuses. Sauter des centaines de milliers de lignes pour atteindre la page 10 000 impacte fortement les performances. Exemple : requête avec offset = 13ms vs requête avec curseur = 0,03ms.
Bonne pratique : Utiliser la pagination par curseur avec des index bien optimisés. Meilleure gestion des performances et pas de problème de décalage entre les pages.
Conseil : Tester différentes méthodes de pagination sur des volumes de données réalistes. Chaque base de données réagit différemment. Adapter l'approche en fonction du contexte.
6. Quand et comment gérer les versions d'API
La première version de l'API fonctionne. Mais dans quelques mois, il faudra ajouter des features ou casser certaines choses pour les améliorer. C'est là que le versioning entre en jeu.
Exemple concret : Stripe utilise des middlewares pour adapter les requêtes et réponses en fonction des versions. Si un utilisateur envoie une requête en version V8, elle sera convertie en V10 avant d'être traitée par l'API.
Vigilance : Ne pas se précipiter pour ajouter du versioning dès la première version. Tant qu'il n'y a pas de deuxième version, le versioning est inutile. Se lancer trop tôt peut fragmenter la base d'utilisateurs.
Bonne pratique : Quand le besoin arrive, utiliser des headers ou des noms de chemins pour gérer les versions (ex: /v2/). Ne pas complexifier dès le départ.
Conseil : La clé d'un bon versioning est la communication. Communiquer en amont avec les utilisateurs lors d'une nouvelle version. Proposer une période de transition. Documenter les breaking changes avec précision.
7. Surveiller et protéger son API
'Les clients disent que l'API est down, c'est normal ?' Si c'est un client qui l'apprend à l'équipe, c'est déjà trop tard pour la réputation du produit.
Exemple concret : Mettre en place du monitoring avec Prometheus et Grafana pour mesurer le temps de réponse de chaque requête et détecter les incidents. Créer des dashboards pour une vue en temps réel de l'état de santé de l'infrastructure.
Bonne pratique : Activer des alertes automatiques qui notifient dès qu'un composant de l'API ne fonctionne pas correctement. Réagir avant que les utilisateurs ne soient impactés.
Vigilance : La sécurisation est aussi importante que le monitoring. Désactiver le port HTTP (80) et imposer HTTPS pour éviter les attaques Man-in-the-Middle. Utiliser des tokens signés pour éviter de vérifier chaque requête en base de données.
Conseil : Ne pas se contenter d'une surveillance réactive. Être proactif en testant régulièrement les endpoints avec Postman ou des scripts de test automatisés pour détecter les problèmes en amont.
8. Navigation dynamique dans les APIs RESTful
HATEOAS (Hypermedia As The Engine Of Application State) est un principe clé des APIs RESTful. Il permet à un client de naviguer dynamiquement à travers les ressources de l'API en suivant les liens hypermédias fournis dans les réponses. Le client n'a pas besoin de connaître à l'avance tous les endpoints.
Avantages : Découplage entre client et serveur. Le client n'a besoin de connaître que l'URL de base et les types de relations. Le serveur pourrait théoriquement changer les URLs sans casser la compatibilité client.
Inconvénients : HATEOAS date de la fin des années 90. Il entraîne une augmentation du nombre de requêtes et donc de la charge. Les clients doivent naviguer séquentiellement. En pratique, les clients écrivent souvent les endpoints directement dans leur code par simplicité.
Bonne pratique : Si HATEOAS est un prérequis : inclure des liens hypermédias pertinents dans toutes les réponses, utiliser des standards (HAL, JSON-LD, SIREN) pour structurer les liens, définir clairement les relations ('rel') pour chaque action.
Conseil : Penser son API comme une application web pour les machines. Fournir une API Reference complète dans la documentation. Laisser les clients ignorer HATEOAS s'ils le souhaitent. C'est une fonctionnalité supplémentaire, pas une contrainte.