Qu’est-ce que la conception d’API ?

La conception d’API inclut des décisions concernant les points de terminaison d’API, les formats de requête et de réponse, les protocoles et la manière dont les API communiquent avec d’autres applications et consommateurs. La conception joue également un rôle important dans la gouvernance des API.

La gouvernance des API désigne l’ensemble de normes, de politiques et de pratiques qui définissent la manière dont une entreprise développe, déploie et utilise ses API. Une conception d’API efficace produit des API qui respectent ces politiques prédéterminées, avec une documentation solide et à jour qui explique le fonctionnement de l’API. Les API bien conçues garantissent une meilleure réutilisation, évolutivité et compatibilité, et offrent une meilleure expérience aux utilisateurs finaux.

Il existe de nombreux cas d’utilisation d’API et de nombreuses approches de la conception d’API, avec certains protocoles, styles d’architecture et langages mieux adaptés à des tâches ou à des cas d’utilisation spécifiques que d’autres.

L’adoption généralisée des API Web a entraîné le développement et l’utilisation de certains protocoles, styles, standards et langages. Ces structures fournissent aux utilisateurs un ensemble de paramètres, ou spécifications API, qui définissent les types de données, les commandes, la syntaxe, etc. En effet, ces protocoles d’API favorisent un échange normalisé d’informations.

Les protocoles, les styles d’architecture et les langages les plus courants sont les suivants :

• SOAP (Simple Object Access Protocol)
• Appel de procédure à distance (RPC)
• WebSocket
• REST (Representational State Transfer)
• GraphQL

Le choix de la bonne structure pour une nouvelle API est un aspect important du processus de conception. Ces protocoles, ces styles d’architecture et ces langages ne sont pas nécessairement meilleurs ou pires les uns que les autres. Ce sont des outils différents qui sont adaptés à des tâches différentes.

SOAP est une spécification de protocole de messagerie légère basée sur XML qui permet aux points de terminaison d’envoyer et de recevoir des données via plusieurs protocoles de communication, notamment SMTP (Simple Mail Transfer Protocol) et HTTP (Hypertext Transfer Protocol). Le protocole SOAP est indépendant, ce qui permet aux API SOAP de partager des informations entre des applications ou des composants logiciels exécutés dans différents environnements ou écrits dans différents langages.

Comparées aux autres types d’API, les API SOAP sont généralement développées de manière plus formalisée et structurée. Les API SOAP existent depuis les années 1990 ; il s’agit d’un format plus ancien et mieux établi, mais également plus lent que les architectures plus modernes comme REST. 

SOAP encode les données au format XML et ne prend pas en charge le transfert de données dans d’autres formats. En revanche, les API SOAP n’ont pas nécessairement besoin du protocole HTTP pour transporter les messages, ce qui leur confère une plus grande souplesse dans le transfert des données. SOAP est considéré comme plus sûr que certains autres protocoles, ce qui rend les API SOAP adaptées aux systèmes qui traitent des données sensibles.

L’appel de procédure à distance (RPC) est un protocole qui fournit le paradigme de communication de haut niveau utilisé dans le système d’exploitation. Le RPC met en œuvre un système de communication client-serveur logique, spécialement conçu pour prendre en charge les applications réseau. Le protocole RPC permet aux utilisateurs d’employer des procédures distantes comme s’il s’agissait de procédures locales. Cela s’avère adapté aux situations qui impliquent de nombreuses interactions client/serveur et une interaction client/serveur.

Les API RPC peuvent être décomposées en XML-RPC, JSON-RPC et gRPC. XML-RPC est un appel de procédure à distance qui utilise un format XML spécifique pour transférer les données. Ces API sont plus anciennes que les API SOAP, mais elles sont simples et légères. JSON-RPC est un appel de procédure à distance qui utilise JSON (JavaScript Object Notation) pour transférer les données. Comme JSON utilise des structures de données universelles, ce format peut être utilisé avec n’importe quel langage de programmation. 

gRPC est un cadre RPC open source haute performance, initialement développé par Google. gRPC utilise le protocole réseau HTTP/2 et le format de données Protocol Buffers. Il est couramment utilisé pour connecter les services d’une architecture de type microservices.

Les API WebSocket permettent une communication bidirectionnelle entre le client et le serveur. Ce type d’API ne nécessite pas de nouvelle connexion à chaque communication : une fois la connexion établie, elle permet un échange continu. Cela fait des API WebSocket une option idéale pour la communication en temps réel. 

Le chat en direct, la localisation en temps réel et la diffusion de données sont d’excellents exemples de cas d’utilisation des API WebSocket. Les API WebSocket permettent également la synchronisation des données, qui consiste à assurer leur cohérence et actualité à travers les appareils ou systèmes, puisqu’elles se mettent à jour en temps réel, sans avoir à créer une nouvelle connexion lors de chaque modification.

REST est un ensemble de principes d’architecture d’API web. Les API REST(également appelées API RESTful) sont des API qui respectent certaines contraintes architecturales REST. Les API REST utilisent des requêtes HTTP telles que GET, PUT, HEAD et DELETE pour interagir avec les ressources. REST présente les données sous forme de ressources, chaque ressource étant représentée par un URI unique. Les clients demandent une ressource en fournissant son URI. Les API REST sont des API sans état : elles n’enregistrent pas les données client entre les requêtes.

Les API RESTful sont populaires car elles sont légères, flexibles et faciles à utiliser. Elles prennent entièrement en charge le transport des messages dans différents formats, comme le texte brut, HTML, YAML, XML et JSON, ainsi que la mise en cache. Bien que cela les rende utiles dans une grande variété de contextes, certaines stations requièrent un langage ou un protocole plus spécifique pour accomplir efficacement une tâche.

GraphQL est un langage de requête et un environnement d’exécution d’API que Meta a développé en interne en 2012 avant de devenir open source en 2015. GraphQL permet aux utilisateurs d’effectuer des requêtes API en quelques lignes seulement, sans avoir à accéder à des points de terminaison complexes avec de nombreux paramètres. Cette capacité peut faciliter la génération de requêtes API et la réponse à ces dernières, en particulier pour les requêtes plus complexes ou spécifiques qui ciblent plusieurs ressources.

Meta a développé ce langage de requête pour rendre ses applications mobiles plus efficaces ; les API GraphQL sont donc adaptées aux applications mobiles. En offrant un point d’entrée unique, les API GraphQL réduisent les temps de chargement en interrogeant les données sans avoir à effectuer plusieurs requêtes au serveur. 

Le processus de conception d’API comporte quatre étapes clés :

• Planifier
• Développer
• Test
• Déployer

Toutes ces étapes impliquent la collaboration des principales parties prenantes. Si certaines étapes conviennent mieux à certaines parties prenantes que d’autres, la conception de l’API doit demeurer un processus collaboratif. Cela permet aux développeurs d’éviter d’ajouter des fonctions dont le programme n’a pas besoin, ce qui accélère le processus de développement dans son ensemble.

La première étape, quel que soit le projet, consiste à s’accorder sur le type d’API à créer. Une API destinée aux clients d’une entreprise de commerce électronique aura des besoins de conception et de fonctionnalité différents de ceux d'une API destinée à être utilisée en interne pour un workflow d’authentification. Il est important que toutes les parties prenantes comprennent les cas d’utilisation de la future API avant la phase de développement.

Comprendre la finalité de ce qu’une entreprise construit (et pourquoi) peut donner aux développeurs une meilleure idée de la manière de le construire, y compris des protocoles à utiliser. Si, par exemple, cette API potentielle nécessite une communication en temps réel, les développeurs savent qu’ils peuvent utiliser WebSocket pour la créer, car ce protocole est bien adapté à cet usage. 

Une fois que les parties prenantes ont une vision claire de ce que sera l’API et de son fonctionnement, il est temps de commencer à la créer. Au cours du processus de développement de l’API, les développeurs définissent les points de terminaison de l’API ; ils conçoivent le modèle de données pour l’API ; ils s’assurent que l’API adhère aux politiques de sécurité des API et renvoie des codes d’état standard pour les erreurs ; si nécessaire, ils mettent en œuvre des mécanismes d’authentification tels que des en-têtes http, des clés API, oauth ou des tokens ; et ils définissent les codes d’erreur, les messages et les réponses.

Une autre partie du processus de développement est la documentation. Pendant que l’API est en cours de création, tous les choix effectués doivent être consignés dans un document lisible par les humains et par machine. Les documents lisibles par les humains sont rédigés dans un langage naturel et facile à comprendre. Un document lisible par une machine doit respecter une spécification API, telle que la spécification OpenAPI, qui normalise le format afin qu’il soit cohérent et puisse être intégré dans des systèmes futurs.

La conception d’API peut être un processus hautement itératif, surtout si les API exposent des données sensibles : il est alors important de les tester rigoureusement pour détecter les bugs et les failles. Après avoir créé un élément, il est important de vérifier qu’il fonctionne comme prévu. Une partie importante du test des API est la simulation, qui est le processus de création de serveurs fictifs avec des données d’échantillon pour vérifier si l’API communique correctement avec ses points de terminaison et renvoie les résultats attendus. 

La simulation peut être effectuée parallèlement aux tests d’API. Les tests d’API incluent des tests de contrats, qui déterminent à quoi doivent ressembler une requête et une réponse ; les tests unitaires, qui confirment qu’un seul point de terminaison fournit la réponse attendue ; les tests de charge, qui consistent à vérifier si l’API est capable de fonctionner en période de pic de trafic ; et les tests de bout en bout, qui valident les parcours utilisateur impliquant la communication avec plusieurs API. Les tests peuvent être effectués manuellement ou en implémentant des cadres de test automatisés.

Si tout fonctionne comme prévu, l’API est prête à être publiée et déployée. À ce stade, il est important que la documentation de l’API soit finalisée afin que les autres utilisateurs et leurs machines puissent intégrer correctement l’API dans leur réseau informatique. Il est possible qu’une fois l’API publiée, les utilisateurs y trouvent des problèmes que les parties prenantes n’avaient pas anticipés. Il est utile de mettre en place une stratégie de gestion des versions avant la sortie de l’API, afin que les développeurs puissent mettre à jour l’application avec cohérence et clarté, le cas échéant.

Une approche du développement d’applications axée sur les API priorise la conception d’API au début du processus de développement logiciel et permet de créer des applications avec des services qui seront fournis via des API. L’idée est qu’en priorisant la conception d’API dès le début du développement logiciel, les API qui en résultent sont réutilisables, plus sûres, plus efficaces, plus faciles à utiliser et mieux alignées sur les objectifs de l’entreprise. Cette approche s’oppose à une approche axée sur le code, qui donne la priorité à la logique du code, les développeurs créant des API pour s’intégrer plus tard aux logiciels. 

La conception d’API est essentielle dans une approche « API-first ». Dans l’approche « API-first », les API sont au cœur du développement d’applications, et une conception bien pensée favorise le développement d’applications plus performantes et plus utiles. 

De solides pratiques de conception d’API peuvent également contribuer à améliorer l’expérience des développeurs et de l’utilisateur final en découvrant et en résolvant les difficultés liées au développement et aux performances avant qu’elles ne se transforment en problèmes plus importants.

Les parties prenantes peuvent établir dès le début du processus de développement que toutes les applications de l’entreprise s’intègrent et fonctionnent bien les unes avec les autres. Lorsqu’elle est mise en œuvre avec succès, une approche orientée API dotée d’une documentation complète permet aux développeurs de réutiliser les API existantes plutôt que de recréer des fonctions existantes.

Les API REST (ou RESTful) ont une structure souple. La seule exigence est de respecter les six principes de conception REST suivants, également appelés contraintes architecturales : interface uniforme, découplage client-serveur, sans état, mise en cache, architecture système en couches et, éventuellement, code à la demande. 

Ces contraintes architecturales font que les API RESTful sont bien adaptées à une approche « API-first » : le découplage client-serveur et l’absence d’état sont particulièrement utiles. 

Dans une API RESTful, les applications client et serveur doivent être distinctes. La seule information que l’application cliente doit connaître est l’identifiant de ressource uniforme (URI) de la ressource demandée ; elle ne peut pas interagir avec l’application serveur d’une autre manière. 

Les API REST sont également sans état, ce qui signifie que chaque requête doit inclure toutes les informations nécessaires à son traitement. En d’autres termes, les API REST ne nécessitent aucune session côté serveur. Ces contraintes rendent ces API indépendantes des serveurs d’une entreprise, ce qui les rend flexibles : les applications client et côté serveur peuvent être écrites avec différents langages et protocoles sans affecter la conception de l’API.

Les API RESTful conviennent également à un environnement API-first, car elles sont évolutives et légères. La séparation entre le client et le serveur améliore l’évolutivité, car les API RESTful n’ont pas besoin de conserver les informations antérieures sur les requêtes client, ce qui réduit les goulots d’étranglement dans la communication. Une mise en cache efficace peut également réduire les interactions client/serveur, un autre atout pour l’évolutivité. Comme les API RESTful utilisent le format HTTP pour transporter les messages, elles peuvent accepter le transfert de données dans plusieurs formats. Cela peut simplifier l’intégration dans de nouveaux environnements.

Les microservices, ou architecture de microservices, sont une approche architecturale cloud native dans laquelle une seule application est composée de nombreux composants ou services plus petits, faiblement couplés et déployables indépendamment. Les API REST sont souvent utilisées pour permettre la communication entre ces services plus petits.

Une approche « API-first » s’intègre bien au schéma architectural des microservices, car les API sont utilisées pour connecter les services entre eux. Si la conception des API est une priorité au sein d’une entreprise et que les API sont conçues pour communiquer de façon fluide les unes avec les autres, les développeurs gagnent du temps lorsqu’ils regroupent ces services au sein d’applications plus vastes. 

Pour tirer le meilleur parti des API, les entreprises mettent souvent l’accent sur les aspects suivants :

• Gouvernance et documentation des API
• Recueillir le feedback des parties prenantes
• Authentification appropriée
• Gestion des versions
• Standardisation des messages d’erreur
• Échelle et contexte
• Cohérence

Ces principes permettent de tenir toutes les parties prenantes informées tout au long du processus de conception des API et de s’assurer que les API s’alignent sur les objectifs et la stratégie de l’entreprise.  

Gouvernance et documentation des API : l’établissement précoce d’une stratégie de gouvernance et de documentation des API à l’échelle de l’entreprise favorise la cohérence et facilite la navigation dans le portefeuille d’API d’une entreprise. Par exemple, une entreprise peut choisir d’adopter une spécification telle que OpenAPI afin que toutes les API d’entreprise adhèrent à une norme applicable à l’ensemble du secteur. Dans tous les cas, le maintien d’une gouvernance et d’une documentation appropriées et cohérentes permet aux nouveaux utilisateurs de l’API de comprendre rapidement l’API et ses fonctions. 

Recueillir les commentaires des parties prenantes : l’entrée précoces des principales parties prenantes et des utilisateurs d’API aident les développeurs à rester sur la bonne voie tout au long du processus de développement. Une mauvaise communication peut entraîner des retards dans le développement des API et des API de moindre valeur.

Authentification appropriée et sécurité de l’API : pour protéger les API ainsi que les données sensibles, les entreprises mettent en œuvre des techniques d’authentification qui permettent de valider les requêtes d’API. Les mécanismes d’authentification tels que les clés API, OAuth et les tokens Web JSON (JWT) offrent différentes méthodes de sécurisation des données et du trafic API. Le chiffrement des API, le processus d’encodage des données pour les déplacements entre le client et le serveur, permet également de protéger les données et les API.

Tests et versions : les tests d’API couvrent divers scénarios, positifs et négatifs, afin d’identifier les problèmes avant qu’une API ne soit déployée. Les API évoluent au cours de ces tests et les développeurs créent de nouvelles versions qui corrigent les bugs ou améliorent la performance. De nouvelles versions d’API sont également publiées pour d’autres raisons, par exemple lorsque des développeurs ajoutent de nouvelles fonctionnalités à une API. La gestion des versions permet aux développeurs de gérer les modifications apportées à une API, de rendre les modifications transparentes et de s’assurer que les mises à jour ne perturbent pas les utilisateurs actuels.

Il est utile de définir des mécanismes de gestion des versions, tels que des versions basée sur les URL ou les en-têtes, avant de commencer sérieusement le développement.

Standardisation des messages d’erreur : une gestion correcte des erreurs améliore l’expérience des utilisateurs d’API, car elle facilite le dépannage en cas de problème. Les codes d’erreur, les messages et les réponses doivent décrire avec précision la nature de l’erreur et rester clairs et cohérents.

Contexte et contraintes : chaque API existe dans un contexte spécifique qui détermine comment elle sera construite et quelles sont ses fonctions. Le respect des délais des projets, les volumes de trafic attendus et le fait que l’entreprise privilégie les API ou le code peuvent façonner l’API qui en résulte. Il est important que toutes les parties prenantes soient conscientes de ces informations afin de pouvoir prendre des décisions éclairées au cours du processus de développement.

Cohérence : avant tout, maintenir la cohérence permet généralement d’améliorer la conception des API. La cohérence dans la conception des API ne se limite pas à la version et aux codes d’erreur. Lors de la définition des points de terminaison, conserver des conventions de dénomination cohérentes peut faciliter leur identification. Lorsque vous faites une requête spécifique à une API, elle doit être résolue de la même manière à chaque fois. Lorsque tout est cohérent dans un environnement d’API, il est également plus facile de documenter les API afin qu’elles soient compréhensibles pour les futurs utilisateurs.