Aller au contenu principal

API Guidance: Aperçu des technologies API partie 2

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.

Dans la première partie de cette série, nous avons déjà abordé les bases des API. 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

Le troisième épisode abordera les instructions de mise en œuvre des API et sera axé sur :

  • les interfaces RESTful ;
  • les interfaces GraphQL ;
  • la conception de la sécurité ;
  • 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.  

 

4. Les types d’API et leurs implications pratiques

Il existe divers types d’API pour aider les microservices et les systèmes autonomes à communiquer entre eux. La section suivante est consacrée à cinq des types d’API les plus importants : SOAP, les interfaces RESTful, GraphQL, les streams/événements et les liens Web.

4.1 SOAP

Le « Simple Object Access Protocol » (SOAP ou WS-SOAP) est un protocole standardisé1 pour les RPC. Les RPC déclenchent une opération entre deux systèmes en utilisant le protocole HTTP(S) et la représentation des données au format XML. Le HTTP(S) sert de protocole de transport sous-jacent pour accéder au point d’entrée d’un service SOAP. Le contenu du message pour la mise en œuvre du RPC se trouve dans les données XML standardisées.

Le SOAP est toujours très utilisé, surtout en raison de sa compatibilité avec les exigences d’interopérabilité spécifiques aux cadres d’application des applications existantes suivant l’approche de l’architecture orientée sur le service (SOA). Il est également considéré comme un avantage en raison de l’immense écosystème SOAP composé de composants techniques et de directives de mise en œuvre. Ils comprennent par exemple les services de sécurité et les politiques technologiques obligatoires dont les projets doivent tenir compte.

Le XML et le SOAP sont encore très présents à l’heure actuelle et sont mis en œuvre dans diverses interfaces et mises en œuvre existantes ou traditionnelles. Mais ce sont aussi des technologies lourdes de plus en plus remplacées par des applications utilisant une approche RESTful ou de microservices. Ce guide des API se concentre sur des approches plus modernes, et n’explore donc pas le SOAP en détail.

 4.2 Interfaces RESTful

Les interfaces RESTful appliquent l’architecture de REpresentational State Transfer (REST) pour permettre à un client (c’est-à-dire, le système demandeur) d’accéder à et de manipuler les représentations textuelles des ressources Web par le biais d’opérations prédéfinies, uniformes et sans état. REST repose sur les liens hypermédia, c’est-à-dire des liens vers d’autres contenus tels que les vidéos, les fichiers audio et du texte au moyen d’hyperliens. Bien que le paradigme ne dépende pas d’un protocole de transport spécifique, les services Web RESTful utilisent fréquemment les opérations fixes du protocole HTTP(S).

En pratique, un lien RESTful renvoie à une ressource ou à un ensemble de ressources hypermédia, comme des livres dans une librairie :

https://my-bookstore.com/store/books

https://my-bookstore.com/store/books/1

Le premier lien permet d’accéder à une liste de tous les livres disponibles, tandis que le second fait référence à un livre précis. Mais, comme mentionné précédemment, les interfaces RESTful n’utilisent pas seulement les URL pour renvoyer à des points d’entrée ou à des ressources, mais aussi pour déclencher des fonctions supplémentaires :

https://my-bookstore.com/store/books/1/numberInStock

Ce lien appelle une fonction qui compte le nombre d’exemplaires d’un livre donné en stock. De la même manière, il est possible d’étendre les liens de manière à répondre à d’autres paramètres, tels que des filtres ou des requêtes concernant un auteur précis :

https://my-bookstore.com/store/books?author=Doyle

Combinés au protocole HTTP, ces liens peuvent définir l’opération à exécuter sur une ressource, par exemple :

GET https://my-bookstore.com/store/books (pour obtenir une liste de livres)

DELETE https://my-bookstore.com/store/books/1 (pour supprimer un livre précis)

POST https://my-bookstore.com/store/books/1 (pour créer un livre dans une certaine liste)

Lorsqu’un livre est envoyé dans une liste, les détails du nouveau livre sont transmis dans la charge utile du corps de la requête POST au format JSON :

{

                                           "title":"4.50 From Paddington. (Miss Marple)",

                                           "author":"Agatha Christie",

                                           "isbn":"978-0007120826"

}

Dans le cas de la requête GET, la liste de livres est contenue dans la charge utile du corps de la réponse GET. À l’appel de méthode HTTP s’ajoutent les métadonnées envoyées dans la requête, ainsi que celles transmises en retour dans la réponse. Ces méta-informations peuvent être présentées dans le format de représentation que l’on suppose être utilisé ou donné, par exemple, JSON

Content-Type: application/json

En plus de ces éléments, chaque réponse HTTP comprend un code d’état. Les codes d’état HTTP sont principalement standardisés, par exemple :

200 OK

En bref, une interface REST basique couvre les cinq éléments principaux suivants :

  1. Le schéma URL, y compris les paramètres
  2. Les méthodes HTTP
  3. Les métadonnées HTTP
  4. La charge utile définie par un schéma de représentation
  5. Les codes d’état

D’autres aspects et des conseils sur la construction d’une bonne interface REST sont disponibles dans de nombreux guides, comme les règles Hypermedia As The Engine Of Application State (HATEOAS).2 Une spécification d’interface complète d’un service peut être définie à l’aide d’une description formelle telle que la proposition standard pour l’OpenAPI 3.3 La description formelle et la documentation des API sera expliquée dans la section 6.

4.3 GraphQL

Alors que WS-SOAP et WS-REST sont des approches génériques pour échanger des données et communiquer dans les systèmes distribués, GraphQL peut aider à récupérer et modifier les données de manière plus flexible et, selon le cas d’utilisation, plus efficace. Dans certains cas, les solutions basées sur WS-SOAP et WS-REST peuvent aboutir à un comportement inefficace. Le plus souvent, cette inefficacité se présente sous la forme de longs allers-retours ainsi que d’une extraction excessive ou insuffisante de données. Le terme « longs allers-retours » décrit simplement une situation dans laquelle la boucle de la requête à la réponse (c’est-à-dire, du client au serveur, puis de retour au client) prend un temps (relativement) long. L’extraction excessive et insuffisante de données désigne quant à elle les situations dans lesquelles les API fournissent trop ou trop peu de données, ce qui peut se produire parallèlement. Par exemple, cela pourrait être le cas avec un utilisateur d’API souhaitant afficher sur son site Web une liste de livres indiquant le titre des livres et les auteurs respectifs, mais qui aurait stocké les livres et les auteurs dans différentes ressources accessibles par des API endpoints distincts (« https:.../boutique/livres » et « https:.../boutique/auteurs »). L’utilisateur demanderait d’abord la liste des livres à l’endpoint correspondant, mais recevrait trop d’informations, comme les ISBN (extraction excessive). Il devrait ensuite appeler l’autre endpoint juste pour demander les noms complets des auteurs (extraction insuffisante).4 Pour faire face à ces problèmes, les fournisseurs d’API peuvent optimiser leurs API en fournissant des méthodes et des solutions de contournement dans l’interface qui correspondent à des cas d’utilisation spécifiques. Mais bien souvent, il y a simplement trop de cas d’utilisations, sans compter le fait que ces cas d’utilisations évoluent rapidement en raison de la création ou de la modification des dossiers commerciaux. L’approche de contournement n’est donc ni assez flexible ni rentable. Dans ce contexte, Facebook a mis au point l’API GraphQL, qui permet notamment aux interfaces utilisateurs d’être adaptées rapidement et de manière flexible sans avoir à adapter trop souvent d’API.

GraphQL utilise le HTTP(S) pour accéder à un point d’entrée. Le point d’entrée GraphQL permet d’extraire les données publiées à l’aide d’un langage de requête simple. Tout d’abord, les fournisseurs d’une API GraphQL doivent fournir un schéma de données global qui contient toutes les entités et méta-informations. Par exemple :

type Author {

                                           name: String

                                           address: String

}

 

type Book {

                                           title: String

                                           isbn: String

                                           authors: [Author]

}

 

type Query {

                                           books: [Book]

                                           book(title: String): Book

}

Un service GraphQL avec ce schéma permet d’obtenir une liste de tous les livres et de leurs auteurs à l’aide de la requête suivante :

{ books { title, authors { name } } }

Il indique également les détails d’un livre donné en utilisant la requête suivante :

                             { book(“Le Train de 16 h 50. (Miss Marple)”) { title, isbn, authors { name } } }

Le schéma GraphQL définit la vue maximale des données à laquelle un client peut accéder par le biais d’un point d’entrée GraphQL. Il n’est pas nécessaire que tous les champs du schéma soient des champs de données réels dans le stockage de données sous-jacent. Par exemple, un champ peut être mis en œuvre en interne par le serveur sous forme de fonction, par exemple « numberOfBooks ». En fournissant la totalité des données disponibles au client par le biais d’une API, un client peut s’adapter rapidement et de manière très flexible à la vue de données dont il a vraiment besoin pour le cas d’utilisation. Les modifications de l’API ne sont nécessaires qu’en cas de changement du schéma de données. Même dans ce cas, un client ne doit être modifié que s’il utilise les champs modifiés.

Un point d’entrée GraphQL pour un certain service est établi en tant que serveur GraphQL. Le serveur GraphQL connaît le schéma de données concerné et évalue une requête GraphQL. En général, le serveur GraphQL ne gère pas les données sous-jacentes lui-même. À la place, il agit plutôt comme un proxy, en mappant efficacement les requêtes sur un système de gestion de base de données existant ou d’autres systèmes de source. En plus de réaliser des requêtes de données, GraphQL permet également de modifier les données et de s’abonner à des flux de messages, ce qui permet aux utilisateurs de données de recevoir immédiatement les informations sur les événements.

En général, il n’y a qu’un seul point d’entrée pour GraphQL. Mais pour des raisons de protection des données, un service pourrait posséder des points d’entrée pour différents rôles. Pour gérer l’accès, ces points d’entrée restreindraient l’accès à certaines entités du schéma pour différents utilisateurs, limitant ainsi leur capacité à extraire des données en fonction de leur rôle.

Pour faciliter le développement des clients, GraphQL offre une mise en œuvre standard d’un terrain de jeu basé sur le Web, qui peut être intégré facilement dans un serveur GraphQL.5 Le terrain de jeu permet de tester les requêtes GraphQL de manière interactive selon les données fournies.

Traiter simplement les données de manière séquentielle et transactionnelle ne permet pas aux applications modernes d’être réactives. Le terme « réactive » signifie qu’une application doit être disponible, souple, résiliente et orientée messages. Selon le Manifeste Réactif, les applications réactives fonctionnent mieux dans les systèmes distribués modernes façonnés par une grande diversité de serveurs ou de machines différents, des téléphones portables aux serveurs à grande échelle, entraînées par les exigences des utilisateurs concernant des temps de réponse de l’ordre de la milliseconde et une disponibilité continue des services[1].6

Figure 2 : Messagerie asynchrone utilisant un bus d’événement et des flux en attente

Figure 2 : Messagerie asynchrone utilisant un bus d’événement et des flux en attente

Les nouvelles conceptions architecturales, comme les systèmes orientés événements, visent à répondre à ces exigences. De plus, les paradigmes tels que la séparation commande-requête (CQRS) permettent aux systèmes distribués de communiquer au moyen de messages asynchrones. Grâce aux messages asynchrones, au lieu d’attendre la suite du traitement jusqu’à ce que le client ait reçu une réponse du serveur, un client peut simplement annoncer un événement à tous les écouteurs intéressés actuellement disponibles. Ces messages peuvent être placés dans une file d’attente dans un flux, ce qui garantit qu’un abonné ou que tous les abonnés lisent chaque message, au moins à leur tour. Essentiellement, cela permet une distribution beaucoup plus efficace des tâches à plusieurs travailleurs. Tout comme les charges utiles des API décrites précédemment, les événements et les flux de messages transportent des informations. Outre l’utilisation d’un service commun pour toutes les parties avec une API bien définie pour le protocole de transport sous-jacent, il est donc important que le format des messages et les sujets/objets des canaux spécifiques soient bien définis et documentés.

4.5 Liens Web

Bien que les différentes technologies de backend soient souvent bien structurées en microservices et en conteneurs, la division du travail au niveau du frontend peut être tout aussi difficile. Tout comme en backend, les cadres d’application frontend, même récents, peuvent évoquer de nouveaux monolithes.  La solution technique consiste à diviser l’interface graphique et à disposer de composants réutilisables et polyglottes, par exemple en utilisant des composants Web et en construisant des micro-frontends.7 Revenons à la Figure 1. Indépendamment d’une mise en œuvre universelle, la division de l’interface en fractions, notamment pour établir les systèmes verticalisés tels que les systèmes autonomes présentés, semble relever du bon sens. En pratique toutefois, cette approche commence tout juste à se propager.

Pour intégrer les systèmes d’interfaces graphiques polyglottes, il est raisonnable d’utiliser des liens Web pour naviguer entre les différentes parties de l’interface graphique (par exemple, micro-frontends) à l’intérieur du frontend général de l’interface graphique. Mais ces liens Web ne sont pas qu’un panneau indicateur vers un point d’entrée. Ils contiennent également des informations contextuelles pour activer un point d’entrée, en modifiant les informations sur un élément spécifique avec un identifiant donné. Quel que soit le cadre d’interface graphique utilisé, il ne devrait pas être difficile de mapper chaque lien Web public au code de composant spécifique en utilisant le routeur HTTP interne du code d’interface graphique applicable.

On peut donc considérer ces liens comme leur propre type d’API. Comme avec les API backend, les API basées sur les liens Web pour des composants d’interface graphique doivent inclure tous les points d’entrée (adresses HTTP) et tous les paramètres pouvant être contenus dans les liens.

Module eLearning pour le chapitre 4

 

5. Les scénarios d’application

Bien entendu, le choix d’un type d’API doit être orienté par les exigences du cas d’utilisation spécifique. Mais dans la pratique, cela est plus facile à dire qu’à faire. En général, il est possible d’utiliser plus d’une technologie API, et il est souvent difficile d’identifier la meilleure solution. Si un service fournit une interface graphique destinée à être utilisée par des parties tierces, le fournisseur doit décrire les liens Web de ces composants d’interface graphique de manière détaillée dans une API.

WS-SOAP et WS-REST sont deux technologies pour échanger des données et des RPC dans les systèmes distribués. Les modifications de ces types d’API sont critiques et déclenchent des adaptations compliquées dans l’écosystème respectif : ces technologies doivent être utilisées pour les cas d’utilisation d’entreprise « stables » avec des logiques métier fixes à long terme, par exemple, les transferts réguliers de données en vrac. Les API WS-REST sont plus légères et doivent donc être utilisées pour les nouvelles API lorsqu’un système est étendu, ainsi que pour les communications internes des systèmes. L’utilisation de WS-SOAP doit être réservée aux API traditionnelles entre organisations indépendantes ; même dans le cas, WS-SOAP devrait continuer d’exister pendant un certain temps, surtout s’il est utilisé dans les normes.

Si les données doivent être fournies de manière souple et agile, en particulier pour les composants d’interfaces graphiques, GraphQL doit être le premier choix. Toutes les communications asynchrones pour mettre en œuvre les architectures orientées événements, l’event-sourcing et la CQRS doivent utiliser les événements et les flux, surtout pour les cas d’utilisation internes. Pour les API publiques, les fournisseurs doivent réfléchir attentivement et décider si le mécanisme de publication/abonnement de GraphQL correspond à leur cas d’utilisation ou si les événements et flux plus avancés conviennent mieux.

Module eLearning pour le chapitre 5

 

6. Documentation

Les API sont le maillon qui relie un service et ses utilisateurs. La meilleure mise en œuvre de service, utilisant les meilleures technologies avancées et solutions créatives, est vouée à l’échec si la documentation de ses API est de mauvaise qualité et réalisée à la va-vite. Un utilisateur, c’est-à-dire un programmeur tiers, doit avoir la possibilité de comprendre correctement l’API pour bien l’utiliser. Par conséquent, une documentation solide, complète et compréhensible est une partie essentielle de chaque API, tout autant que la mise en œuvre robuste et solide du service en lui-même.

Pour cela, la documentation du code source et une documentation des commentaires du code source ne suffisent pas. Les API publiques étant utilisées pour connecter des services distribués rédigés par plusieurs parties, les langages de programmation utilisés par leurs outils diffèrent souvent. Par conséquent, les API doivent soutenir un environnement polyglotte, et donc être définies sous une forme neutre, être formalisées et utiliser une sémantique unique. L’utilisation de langages de définition de schémas comme OpenAPI8 peut garantir cela. Ce langage de description d’interface convient particulièrement aux API REST, mais il peut également être utilisé pour les liens Web, les événements/flux et GraphQL. On peut aussi utiliser une description d’interface basée sur OpenAPI pour générer de la documentation conviviale et du code pour les mises en œuvre des serveurs et des clients. Cela peut aider à générer une mise en œuvre et une documentation cohérentes de l’API.

Au-delà de la description syntaxique et informelle de l’API, on doit trouver une explication de son comportement. Pour cela, on peut fournir des modèles/diagrammes standardisés, par exemple avec « Business Process Model and Notation »9 (BPMN) ou des diagrammes de séquence du « Langage de modélisation unifié »10 (UML). Une autre description importante du comportement doit être établie par un ensemble complet de cas de test, par exemple en utilisant une approche de développement orientée comportement pour le test de l’API.11

Module eLearning pour le chapitre 6

 

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 2
Crédit d'image:
(C) 2020 Support Centre for Data Sharing