API design : les fondamentaux à connaître

La simplicité est un principe fondamental en API design. Pour qu'une API soit facile à prendre en main, il est recommandé de limiter le nombre d'endpoints aux fonctionnalités réellement nécessaires, idéalement moins d'une vingtaine (voir notre article sur l'API Management). L'arborescence des URLs doit suivre une logique cohérente, sans complexité superflue. Par exemple, /clients/{id_client}/commandes est préférable à /commandes?client={id_client}. Les noms d'endpoints et de paramètres doivent être explicites et refléter précisément leur rôle. Les formats de données doivent être standards et sans information inutile, JSON et XML étant les plus courants. Enfin, la documentation se doit d'être concise et illustrée par des exemples concrets facilitant la prise en main.

La cohérence est également primordiale pour le développeur. Les nommages des endpoints et paramètres doivent suivre des conventions clairement définies. Les codes de statut HTTP renvoyés doivent avoir une signification cohérente, par exemple 200 OK pour une requête réussie et 404 Not Found pour une ressource inexistante. Les formats de données doivent rester les mêmes pour des cas d'usage similaires, sans mélanger JSON et XML par exemple. Enfin, les méthodes HTTP utilisées doivent correspondre aux conventions établies : GET pour lire, POST pour créer, PUT pour modifier et DELETE pour supprimer.

L'API doit également être conçue pour pouvoir évoluer facilement sans impacter les clients existants. La dépréciation d'endpoints sera annoncée en avance et les anciennes versions maintenues pendant un temps. L'ajout de nouveaux endpoints ne nécessitera pas de modifications côté client. Les nouvelles fonctionnalités seront implémentées en versionnant l'API plutôt qu'en modifiant les endpoints existants.

Enfin, l'API doit pouvoir être testée simplement. Un environnement de test identique à la production sera fourni. Des jeux de données de test couvrant tous les cas d'usage seront créés. L'API renverra des réponses prévisibles et stables pour simplifier les tests. Des outils de mock pourront également être mis à disposition pour stimuler l'API sans système réel.

• La méthode HTTP (GET, POST, etc.) ;
• L'URL exacte ;
• Les paramètres possibles avec leur type de données ;
• Un exemple de requête ;
• Un exemple de réponse ;
• Les codes d'erreur possibles.

• Exemples d'appels pour les cas d'usage principaux ;
• Snippets de code dans différents langages ;
• Tutoriels pas-à-pas pour les intégrations courantes.

• Architecture et technologies employées ;
• Formats de données utilisés ;
• Processus d'authentification ;
• Limites techniques à connaître ;
• Bonnes pratiques pour une utilisation optimale.

• Nouvelles versions et fonctionnalités ;
• Changements effectués sur les endpoints ;
• Dépréciations et suppressions ;
• Corrections de bugs ;
• Notes de version détaillées.

Pour finir, il doit contenir un glossaire des termes et concepts clés détaillant les moyens d'obtenir de l'aide et le support nécessaire (voir notre article sur l'API Platform).
La documentation doit être précise, complète, cohérente et toujours tenue à jour. Elle peut être rédigée de manière statique ou générée dynamiquement via des outils comme Swagger. L'idéal est de la rendre disponible sous différents formats (HTML, PDF, README...) et facilement accessible depuis l'API elle-même.

Pour concevoir une API facile à utiliser et maintenir, il est recommandé d'appliquer un certain nombre de bonnes pratiques éprouvées.
Tout d'abord, les URLs et noms d'endpoints doivent être explicites et refléter précisément les ressources auxquelles ils donnent accès. Par exemple, utiliser /clients/12345/commandes plutôt que /commandes?idclient=12345. Les nommages doivent rester cohérents dans toute l'API pour faciliter la mémorisation.
Les méthodes HTTP standards doivent être privilégiées, en utilisant GET pour récupérer des ressources, POST pour en créer, PUT pour les modifier et DELETE pour les supprimer. Elles apportent une sémantique claire sur l'action effectuée.
L'API doit renvoyer des codes de statut HTTP en accord avec l'issue de la requête. Par exemple, 200 OK pour une requête réussie, 404 Not Found pour une ressource inexistante ou 400 Bad Request en cas d'erreur côté client.
Les données envoyées par le client doivent être validées et filtrées côté serveur pour garantir leur conformité. L'API doit également implémenter des mesures de protection contre la saturation et les attaques.
Pour les résultats volumineux, la pagination doit être mise en place plutôt que de renvoyer d'énormes réponses. Des paramètres de pagination standards doivent être supportés.
Il est recommandé de versionner l'API dès le départ pour gérer son évolution, plutôt que de modifier des endpoints existants qui risqueraient d'impacter les clients. Versionner une API consiste à publier différentes versions de l'API avec des numéros de version uniques (v1, v2, etc). Chaque version expose un ensemble d'endpoints, de fonctionnalités et de spécifications stables.
En suivant ces bonnes pratiques éprouvées, on obtient une API bien conçue, facile à comprendre et à utiliser de manière optimale pour les développeurs. Cela réduit les bugs, accélère l'intégration et améliore l'expérience développeur.
Connectez rapidement vos périphériques, applications ou données dans le cloud ou sur site avec MuleSoft Anypoint Platform.

Il existe de nombreux formats et protocoles pour concevoir des APIs, chacun avec leurs forces et faiblesses. Les plus utilisés sont REST, GraphQL, SOAP et RPC.
REST (Representational State Transfer) est aujourd'hui le format le plus populaire pour les APIs web. Il repose sur les standards HTTP et HTTPS et les principes d'architecture REST. Il permet de manipuler des ressources via des URLs et des méthodes HTTP standardisées. REST favorise la simplicité, l'extensibilité et l'interopérabilité. Cependant, il peut nécessiter plusieurs appels pour récupérer différentes données.
GraphQL est un format plus récent qui permet de construire des queries précises pour ne sélectionner que les données désirées. Cela évite les appels multiples et les données inutiles. GraphQL ne suit pas les principes REST et utilise un système de types pour définir les données disponibles. Il offre une grande flexibilité, mais requiert plus d'efforts pour la conception de l'API.
SOAP (Simple Object Access Protocol) est un protocole plus strict qui repose sur le standard XML pour structurer les messages. Il définit un format précis avec validation des données. SOAP convient aux APIs complexes nécessitant transactions et gestion d'états. Mais il peut être plus lourd et complexe à utiliser.
Enfin RPC (Remote Procedure Call) permet d'exposer des services et fonctions à distance comme des appels de procédures locaux. Il est bien adapté pour les traitements transactionnels. Mais RPC ne suit pas les standards du web et n'est pas orienté ressource.
Le choix du format dépend donc avant tout des besoins en termes de flexibilité, performance, complexité des traitements, et interopérabilité. Certains formats peuvent aussi être combinés pour tirer parti de leurs avantages respectifs.

Les performances et la scalabilité sont des critères cruciaux lors de la conception d'une API. Une API lente et ne pouvant pas monter en charge rendra l'expérience développeur très mauvaise et impactera négativement les applications l'utilisant.
Plusieurs techniques permettent d'optimiser les performances :

• La mise en cache des réponses côté serveur évite de répéter des traitements coûteux et accélère les réponses aux requêtes récurrentes. Les entêtes HTTP de cache doivent être configurés correctement ;
• La pagination des résultats volumineux évite de renvoyer des réponses de taille excessive qui monopolisent bande passante et capacité serveur. Il est préférable de renvoyer des pages de résultats raisonnables ;
• Le traitement asynchrone et la file d'attente des requêtes permettent d'absorber des charges élevées sans saturation. Les requêtes sont traitées en arrière-plan et les réponses renvoyées de manière différée ;
• L'utilisation d'un réseau de distribution de contenu (CDN) déporte la charge et rapproche géographiquement les données des utilisateurs ;
• La limitation du débit des appels évite les saturations soudaines en lissant la charge dans le temps.

Pour la scalabilité, l'API doit pouvoir monter en charge grâce à :

• Une infrastructure évolutive autoadaptative ajoutant des ressources à la demande ;
• Un déploiement serverless sans serveur fixe, idéal pour absorber des pics de charge ;
• Une architecture microservices décomposant l'application en services indépendants ;
• Des bases de données horizontalement scalables type NoSQL.

En surveillant les métriques de performance et en testant la charge, l'infrastructure peut être renforcée avant saturation. Une API scalable et performante améliore ainsi la qualité de service.

La sécurité est importante pour toute API exposée publiquement. Plusieurs bonnes pratiques et mécanismes permettent de sécuriser une API contre les usages abusifs ou malveillants :
L'authentification des requêtes doit être implémentée pour identifier et autoriser les clients. OAuth 2.0 est le standard de facto, permettant la génération de tokens d'accès temporaires sans partager les identifiants réels. Les tokens doivent être invalidés rapidement et renouvelés fréquemment.
Le chiffrement des échanges via HTTPS empêche l'interception des communications et la compromission des tokens. HTTP Strict Transport Security (HSTS) renforce la sécurité.
La validation et le filtrage des entrées côté serveur protègent contre les injections et données mal formatées. Une bibliothèque éprouvée doit être utilisée.
Les droits d'accès doivent être restreints pour chaque token d'API en fonction des besoins. Le principe du moindre privilège doit être appliqué.
La journalisation et le monitoring des appels à l'API permettent la détection d'anomalies et l'analyse forensique en cas d'incident.
Des tests d'intrusion réguliers par une société spécialisée aident à identifier les vulnérabilités avant leur exploitation.
En appliquant ces bonnes pratiques de sécurité à chaque étape du développement, il est possible de garantir une API sécurisée et conforme aux exigences du marché.