L’utilisation des interfaces de programmation applicative (APIs) s’est généralisée. En effet, les APIs simplifient considérablement l’intégration et la communication de logiciels et applications entre eux. Ainsi, la conception d’une API, lorsqu’elle est minutieuse, impacte positivement sa qualité et sa performance. Mais à quoi reconnaît-on une bonne API ? Quelles sont les bonnes pratiques à suivre lors de la conception d’une API ?
Qu’est-ce qu’une bonne API ?
Une API est bien conçue lorsqu’elle répond efficacement aux besoins et aux usages des utilisateurs. C’est-à-dire des développeurs web qui s’en serviront pour faire communiquer leurs programmes et leurs systèmes. Mais aussi des utilisateurs finaux qui auront besoin d’indiquer, par exemple, leurs données bancaires à un site e-commerce pour réaliser un achat. S’ils n’ont aucune idée de ce qui se passe en back-office du site, ils seront par contre très contrariés qu’un bug les empêchent d’acquérir l’article soldé convoité avant l’épuisement du stock.
Cependant, revenons à nos utilisateurs directs : les services informatiques des entreprises. Choisir une API existante plutôt que de passer par un développement interne a pour objectif de gagner du temps et de simplifier le travail des équipes. Par conséquent, une API bien conçue suppose qu’elle est lisible par les développeurs informatiques et cohérente dans sa construction. De même, parce qu’un bug prolongé entraînerait une baisse de productivité et potentiellement une perte financière, l’API utilisée doit être fiable. Ne parlons même pas des questions de sécurité ! Enfin, une bonne API offre de la flexibilité aux équipes IT pour répondre aux besoins d’innovation.
Comment concevoir une API de qualité ?
Appuyez-vous sur les standards et conventions
Dans un précédent article sur le fonctionnement des APIs, nous avions notamment évoqué les différents protocoles et formats de données associés. Encore une fois, c’est l’usage qui doit guider vos processus métier concernant le type d’API et l’architecture à construire. Pour chaque projet, vous devrez vous pencher sur : le cas d’utilisation, le profil des personnes qui se serviront de vos APIs ainsi que les systèmes auxquels elles devront se connecter. Dans la pratique, l’architecture REST (Representational State Transfer) est souvent utilisée pour sa simplicité et sa flexibilité. De même, elle est compatible avec les protocoles web existants et prend en charge les langages informatiques les plus répandus : HTTP, JSON ou XML.
D’autre part, nous vous conseillons de suivre les conventions en matière de nommage. Pour une expérience fluide des développeurs avec l’API conçue, tous les noms descriptifs des méthodes, ressources, collections, paramètres, champs et réponses doivent être simples, intuitifs et cohérents. Ces conventions de nommage sont nécessaires pour permettre à une majorité de développeurs de comprendre l’API et pour que la connaissance perdure sans ambiguïté. On évitera donc les noms à rallonge ou trop généraux par rapport aux concepts auxquels ils renvoient. Par ailleurs, ce même principe est à appliquer dans la construction des URLs.
Créez une documentation claire, complète et centralisée
Pensez à la documentation et à son actualisation dès la conception de votre API. Plus celle-ci sera complète, plus les développeurs pourront l’implémenter aisément. Elle joue donc un rôle essentiel dans le succès de votre interface de programmation applicative.
Que contient une documentation efficace ? Voici quelques informations à y intégrer :
- liste des paramètres avec toutes les spécifications (endpoints, descriptions, formats) ;
- description des réponses pour chaque point de terminaison ;
- exemples de réponse (y compris de message d’erreur) ;
- exemples de code ;
- expériences de test ;
- données d’authentification.
Aujourd’hui, de nombreux outils de documentation existent pour vous faciliter cette tâche quelque peu rébarbative (SwaggerHub, OpenAPI, etc.).
Testez votre API pendant les phases de développement de l’interface
Le test API est indispensable tout au long du processus de développement. En effet, les tests vont permettre de vérifier que l’API est fonctionnelle et conforme aux enjeux de sécurisation et de fiabilité. Vous pourrez ainsi identifier rapidement les erreurs et les corriger. Le test consistera généralement à effectuer des requêtes à un ou plusieurs points de terminaison et de comparer la réponse obtenue à la réponse attendue. Plusieurs types de tests peuvent être effectués parmi lesquels : test de validation, test fonctionnel, test de charge, test de fiabilité, test de sécurité, test de pénétration, détection d’erreurs…
Ici encore des outils de test automatisé existent pour vous accompagner dans ce processus tels que Postman, Sandbox ou Insomnia.
Veillez à la sécurité
Bien évidemment, l’utilisation de votre API ne doit pas mettre en danger les infrastructures des utilisateurs après l’intégration de votre solution. Le niveau de sécurité est donc un prérequis pour favoriser l’adoption de votre API. Dans un contexte où toutes les entreprises et utilisateurs sont sensibilisés aux questions de cybersécurité. L’emploi de protocoles de sécurité de type SSL est préconisé, de même que le chiffrement ou la mise en place de jetons de sécurité (Security Token) pour l’authentification aux deux extrémités de la communication.
Le conseil en plus d’Axialys
Axialys développe des APIs pour faciliter à ses clients l’implémentation de ses solutions avec leurs outils maison ou applications web. Et cela en toute autonomie. Ainsi, ils sont en mesure de récupérer aisément les statistiques du Logiciel Call Center pour piloter en temps réel l’activité avec des tableaux de bord. De même, s’ils ont un CRM créé en interne, ils pourront intégrer le bandeau agent à celui-ci pour simplifier le quotidien de leurs conseillers.
Cyril Chambellan, Head of Product chez Axialys, nous a partagé une autre bonne pratique à adopter lors de la conception d’une API. Pour lui, la constitution de Modèles d’Objets Métier (Business Object Models) est primordiale dans la gestion de projet applicatif. L’API devant aider à manipuler un objet, les propriétés de chaque objet doivent être définies. Il faudra donc également définir les liens entre ces différents éléments. Chez Axialys, ce travail a été fait en amont de la conception des APIs pour tous les objets comme par exemple le résumé d’appel ou le détail de communication. À la clé, la cohérence, la clarté et la fiabilité des APIs et l’interopérabilité entre différents systèmes d’information.
