Skip to main content

API Guidance: Aperçu des technologies API partie 1

Les interfaces de programmation (API) font partie intégrante des systèmes distribués modernes et constituent un maillon essentiel dans la chaîne d’approvisionnement en données dans les organisations modernes axées sur les données. Elles sont donc indispensables dans l’écosystème de partage des données que le Centre de soutien pour le partage de données cherche à favoriser. Dans cette série en trois parties, accompagnée de modules de formation en ligne, nous avons pour objectif de fournir des connaissances regroupées et pratiques aux personnes qui envisagent de développer et de déployer une API et ont donc besoin de comprendre les bases de cette technologie, ainsi qu’à celles qui recherchent des informations supplémentaires sur les facteurs dont il faut tenir compte dans le processus de mise en œuvre.

Ce contenu sera publié de deux manières :

  1. Ici, sur ce site Web, sous la forme d’épisodes publiés chaque mois ; et
  2. une fois la série terminée, dans un seul document que vous pourrez télécharger et lire hors-ligne.

Le guide est disponible en anglais, en français et en allemand. Chaque épisode est suivi de modules de formation en ligne concernant les sujets abordés respectivement dans chaque épisode, pour vous aider à tester vos connaissances.

Voici les chapitres du premier épisode :

  • Introduction aux API
  • Concepts sous-jacents aux API
  • Les API et leur évolution architecturale

Le deuxième épisode portera sur les sujets suivants :

  • Les types d’API et leurs implications pratiques
  • Les scénarios d’application
  • La documentation sur les API

Restez à l’écoute et n’oubliez pas de discuter du matériel en commentant chaque épisode, ou avec vos pairs sur notre forum.  

 

1. Un défi : partager des données entre des machines

Il existe de nombreuses manières différentes d’échanger des données. Lorsqu’elles sont échangées de façon numérique, il est important de comprendre avec qui ces données sont échangées : l’échange de données se fait-il d’humain à humain ? D’une machine à un humain ? Ou seulement d’une machine à une autre ?

Naturellement, des exigences différentes s’appliquent au partage de données entre humains ou entre humains et machines et au partage de données entre machines. Les humains peuvent souvent comprendre les données quel que soit leur mode de présentation. Un entraînement peut être utile, mais en général, les humains parviennent à comprendre assez facilement les données présentées dans des tableaux, des graphiques, des textes complets et d’autres formats. Surtout, ils en sont capables même si le contexte des données est inconnu.

Les capacités des machines sont bien plus limitées : sans instructions spécifiques, elles ne peuvent pas associer les données qu’elles reçoivent aux informations ne faisant pas partie de ces données. En l’absence d’instructions préalables, elles ont également du mal à comprendre le contexte ou à savoir comment lire les données. En principe, il est donc nécessaire de former les machines ou de leur fournir des instructions relatives à chaque fichier de données qu’elles traitent.

Ainsi, lors du partage de données entre des machines, les deux parties (client et serveur) doivent conclure une forme de contrat technique qui régule les caractéristiques des données et les conditions de leur partage. Les deux parties doivent connaître à l’avance la structure des données et les informations sémantiques qui se cachent derrière les données.

Les API peuvent offrir ces fonctions et permettre un échange de données fluide d’une machine à une autre. C’est pour cette raison qu’elles sont de plus en plus adoptées par toutes sortes d’utilisateurs qui souhaitent partager des données. Malheureusement, les API ne sont pas fournies prêtes à l’emploi. Pour bien fonctionner, elles doivent être rédigées soigneusement par des développeurs bien informés. Ce rapport a pour objectif de faciliter la prolifération d’API de qualité. Dans les sections ci-dessous, il présente les API basées sur le Web et aborde leurs concepts sous-jacents.

eLearning Chapitre 1

 

2. Concepts sous-jacents

Pour comprendre les technologies API modernes, il est essentiel de commencer par comprendre quelques concepts fondamentaux. Les API font partie de tous les systèmes distribués modernes. Pour faire simple, ce sont des interfaces qui standardisent et simplifient l’interaction entre les différents composants, comme plusieurs serveurs, dans un système global. Les API permettent aux composants d’un système distribué de se demander mutuellement des calculs par le biais d’interfaces dans une relation client-serveur. Pour chaque appel, le service demandeur est le client, et le service qui fournit un programme est le serveur. Au-delà de ce principe de base, il est également important de comprendre les concepts de protocole HTTP, d’URL, de formats de représentation des données et de méthodes de communication prédéfinies.

2.1 HTTP

Le « Hypertext Transfer Protocol » (HTTP) et les liens Web fournis par des « Uniform Resource Locators »1 (URL) sont probablement les concepts les plus fondamentaux qui soutiennent « le Web ». Le HTTP n’est pas seulement essentiel pour naviguer sur le Web, mais aussi pour toute messagerie et tout transfert de données entre des systèmes connectés au Web. Ainsi, le HTTP sert également de couche de transport de base pour les API modernes. C’est un protocole basé sur le texte facile à lire et à comprendre pour les humains. De plus, outre le fait de faciliter le contrôle d’une session de communication, il permet à un client et à un serveur, dans un cycle de requête/réponse, d’échanger des messages contenant à la fois des méta-informations dans l’en-tête et la charge utile effective dans le corps. Cette charge utile peut se composer de données ou de code exécutable, ou d’une combinaison des deux.

Il est possible de sécuriser la communication HTTP en encapsulant une session de communication à l’aide d’un mécanisme « Transport Layer Security » (TLS). Aujourd’hui, le protocole TLS est déployé en combinaison avec le HTTP, formant ainsi le HTTPS, qui est une version sécurisée du HTTP. Le HTTPS est essentiel pour s’assurer que la communication ne peut être interceptée ni par des utilisateurs externes ni par des utilisateurs internes.

2.2 URL

En bref, une URL est la forme universelle d’une adresse sur le Web, plus communément connue pour les sites Web. Dans le contexte des API modernes, toutefois, une URL peut également être l’adresse des points d’entrée et des fonctions d’un serveur ou d’une ressource (multimédia). WS-SOAP et GraphQL sont des exemples d’API utilisant seulement les URL comme adresse d’un point d’entrée. Les interfaces RESTful, quant à elles, utilisent des URL contenant des paramètres de base pour déclencher des fonctions définies dans une API, par exemple, récupérer des données spécifiques dans une base de données.

2.3 Format de représentation des données

En plus du protocole de communication, c’est-à-dire la manière dont un message est transféré entre deux points d’entrée (ou plus), il est également important de comprendre comment le contenu effectif d’un message, la charge utile de données, est représenté. Pour obtenir une solution relativement simple, les utilisateurs peuvent déployer des formulaires HTML pour les données structurées, du texte brut (Base64) ou des données chiffrées (Binary Large Object, Blob). En pratique cependant, d’autres formats de représentation des données sont utilisés, notamment pour les données structurées en profondeur :

  • XML (Extensible Markup Language2) : un langage fortement typé pour représenter les données structurées à l’aide de balises et d’attributs, par exemple :

<message lang="de">Hallo</message>

  • JSON (JavaScript Object Notation3) : une notation d’objet légère qui utilise des crochets imbriqués et des propriétés, par exemple :

{ "message": { "text": "Hallo", "lang":"de" } }

  • YAML (YAML Ain’t Markup Language4) : une notation d’objet légère utilisant des lignes en retrait et des propriétés, par exemple :

message:

text: Hallo

lang: de

Le XML est principalement utilisé par l’approche WS-SOAP, tandis que les langages plus légers que sont JSON et YAML sont utilisés par WS-REST et GraphQL.

2.4 Méthodes prédéfinies

Le Web est conçu pour traiter différentes ressources, telles que des éléments de données, des objets multimédia, des objets d’entreprise ou du texte brut, de manière uniforme. Pour maintenir ce principe, le protocole HTTP possède quatre méthodes agnostiques prédéfinies qui peuvent être utilisées pour divers objets et méthodes ; de préférence, ces méthodes doivent être utilisées pour définir une API :

  • POST, pour créer ou envoyer un objet, par exemple dans une autre base de données ;
  • GET, pour lire un objet, par exemple à partir d’une base de données ;
  • PUT/PATCH, pour mettre un objet à jour;
  • DELETE, pour supprimer un objet.

eLearning Chapitre 2

 

3. Les API et leur évolution architecturale

Les systèmes logiciels ne cessent de se complexifier, et leur architecture est donc elle aussi en constante évolution. C’est pourquoi il est de plus en plus important de structurer les logiciels en parties qu’il est possible de gérer. Cette section explore l’interaction entre l’évolution de l’architecture des systèmes logiciels et les API.

Les unités de programmation de base qui structurent les logiciels sont les modules et les bibliothèques. Lorsque les systèmes logiciels, de systèmes singuliers, sont devenus des systèmes distribués, des composants associés de manière souple se sont ajoutés à la liste. La communication entre les composants distribués était assurée par des « appels de procédure distants » (RPC)5. En substance, un RPC est un protocole permettant au programme « A » d’un ordinateur d’envoyer un message exécutable à un autre programme « B » devant se trouver sur le même réseau.  Ainsi, le programme « A » (le client) peut demander au programme « B » (le serveur) de fournir un certain service ou un certain calcul.

À l’origine, les RPC se limitaient principalement à un environnement de programmation homogène et à un cadre d’application spécifique, par exemple, « RMI Java ». Mais avec la croissance des systèmes logiciels, les composants distribués ont évolué en services indépendants et le paradigme de l’architecture orientée sur le service (SOA) s’est popularisé. Dans le paradigme SOA, chaque service a un axe fonctionnel et une responsabilité clairs. Cet axe est devenu de plus en plus présent avec la deuxième génération de SOA, souvent appelée « Conception axée sur le domaine »6 (DDD) et « microservices »7. Ici, la limite d’un service est principalement définie par son domaine central, des interfaces bien définies (API) et la responsabilité organisationnelle dans une équipe entièrement responsable d’un service.

Essentiellement, l’évolution de systèmes logiciels basés sur des composants distribués simples en systèmes logiciels basés sur des services complets a largement renforcé l’important des API en tant que connecteurs. Au fil de cette évolution, il est également devenu évident que différents types d’API sont nécessaires pour différentes tâches techniques.

Selon la « conception axée sur le domaine », un ou plusieurs microservices forment un domaine en tant que « service ». Ces services peuvent avoir des limites claires et peuvent être regroupés avec les données qu’ils gèrent. Un service fournit généralement une ou plusieurs API à d’autres services pour interopérer avec ces derniers. Il est également commun qu’un service soit regroupé avec un micro-frontend pour offrir une interface graphique aux utilisateurs. Un ensemble de logique, de données et de frontend constitue ce que l’on appelle un système autonome8 (SCS). D’un point de vue organisationnel, une seule équipe dédiée devrait toujours être responsable d’un SCS.

La Figure 1 illustre une architecture SCS. Elle représente les systèmes autonomes sous la forme de cubes empilés. Chaque cube se compose des couches architecturales typiques : données, logique métier (vue) et frontend. Les blocs sont autonomes, car ils ne reposent sur aucune ressource externe pour fonctionner. On peut voir une intégration de tous les systèmes ensemble comme une application, par exemple, une boutique Web.Figure 1 : Systèmes autonomes

Figure 1 : Systèmes autonomes

La Figure 1 montre également que les services et les SCS peuvent communiquer l’un avec l’autre de plusieurs manières. Par exemple, un lien Web dans l’interface graphique peut être utilisé pour permettre aux utilisateurs de passer à une nouvelle transaction métier dans l’interface utilisateur : afficher des données, créer un élément, et bien plus encore. L’approche classique consiste à faire communiquer ces systèmes entre eux de manière synchrone à l’aide d’interfaces RESTful.9 Toutefois, dans certains cas, un mode de communication asynchrone peut être préférable. La communication asynchrone implique que l’expéditeur d’une requête n’attend pas que le destinataire réponde à un appel, par exemple, lorsqu’un système demande à un autre d’écrire des données dans sa base de données. Au lieu de ne plus programmer d’autres processus, ce qui bloque le processeur, jusqu’à ce qu’une réponse soit reçue (par exemple, pour dire que les données ont été écrites dans la base de données du système destinataire), le système de requêtes en communication asynchrone continue immédiatement à traiter les autres appels. En général, cette approche aide à économiser la capacité du processeur et à mieux la gérer. Elle comporte toutefois des inconvénients, comme des temps de réponse plus lents une fois une réponse à la requête reçue. En règle générale, cela attire les utilisateurs ayant besoin d’une lecture fiable des données d’une autre base de données vers la communication synchrone. Cela peut être le cas pour les données en temps réel, par exemple lors des mises à jour des prévisions météorologiques en continu.

Quelles que soient leurs performances techniques, il est essentiel que les interfaces API soient bien définies afin de demeurer des parties maintenables et réutilisables d’un écosystème complexe. Cela signifie qu’une API doit :

  • avoir une spécification formelle complète, ainsi qu’une documentation complète intégrale, compréhensible, cohérente et correcte ;
  • avoir un ensemble complet d’exigences contraignantes écrites ne présentant aucune ambiguïté et ne laissant aucun doute à l’utilisateur quant à leur signification.

Lorsque les ordinateurs et les systèmes informatiques ont commencé à émerger, il n’existait qu’une poignée de langages de programmation et d’environnements d’exécution. Aujourd’hui, cet environnement est devenu beaucoup plus complexe. L’un des moteurs principaux de ce développement est le dogme selon lequel il faut utiliser le meilleur outil pour résoudre un problème. Cela a abouti à une prolifération des outils et des langages de programmation, ce qui signifie que le monde de la programmation a dû élaborer des moyens de gérer plusieurs langages à la fois, autrement dit, de devenir polyglotte.

Quelles sont les conséquences de cette évolution pour la définition et la mise en œuvre d’une API ? Il faut se souvenir qu’une API est en essence une interface conçue pour soutenir le transfert de données entre plusieurs systèmes ou services, quels que soient les langages de programmation utilisés par ces systèmes. Par conséquent, l’interopérabilité, c’est-à-dire la capacité à travailler avec différents systèmes et langages de programmation, doit toujours être importante. En pratique, cela signifie que les API bien conçues doivent garantir que les systèmes impliqués dans le transfert de données peuvent utiliser différents langages de programmation. Pour cela, l’idéal est d’utiliser des API de programmation avec un langage de définition de schéma neutre, comme le Web Service Description Language10 (WSDL) pour les API basées sur WS-SOAP.

Mais bien que cette approche soit indubitablement préférable et supérieure d’un point de vue dogmatique, elle comporte également de nombreuses difficultés pratiques. En réalité, la plupart des API ne sont pas définies selon l’approche « API d’abord » qui conçoit les API selon des termes agnostiques. Malheureusement, les spécifications et les documentations sont souvent dérivées du code source du cadre d’application utilisé par le service ou le système auquel l’API est rattachée ; par exemple une définition de classe Java. Au premier abord, cela peut être une solution rapide et pratique pour définir des API adéquates pour le système d’origine. En fin de compte toutefois, cela signifie que ces API sont spécifiques au langage de programmation et au cadre d’application, et souvent mal documentées. En conséquence de ce déplorable statu quo, il existe une forte demande de retour à l’approche « API d’abord »11, qui repose sur la supposition que cela aiderait les développeurs à utiliser les API plus facilement, et donc avec plus de succès. Suivre l’approche « API d’abord » signifie que l’API doit être créée et documentée en premier à l’aide d’un langage de définition de schéma et de spécifications riches, comme OpenAPI12, pour générer le code requis (dans le langage préféré) et écrire une documentation complète. On suppose que le fait de suivre ce principe contribuera à la création d’API interopérables, et donc de meilleures API.

eLearning Chaptire 3

 

 
Restez à l’écoute et n’oubliez pas de discuter du matériel en commentant chaque épisode, ou avec vos pairs sur notre forum. Testez également vos connaissances dans les modules d'apprentissage en ligne de l'API SCDS: https://elearningcourses.eudatasharing.eu/fr/apiguidance/#/
 

API Guidance: Aperçu des technologies API partie 1
Image credit:
Support Centre for Data Sharing