Sélection de la langue

Gouvernement du Canada / Government of Canada

Recherche

Orientation sur la portée et la conception des API

Sur cette page

But

Le présent document traite de certaines considérations clés et des pratiques exemplaires lors de la définition d’une API, ainsi que de sa portée et de sa conception fonctionnelle. Il traite des sujets suivants :

  1. Quels sont les cas d’utilisation judicieuse pour les API par rapport aux cas d’utilisation inappropriée?
  2. Quelles fonctionnalités devez-vous mettre dans une seule API?
  3. Comment gérez-vous les API composites?
  4. Comment gérez-vous le dimensionnement et la mise à l’échelle?

Cas d’utilisation de l’API

Les API sont les mieux adaptées aux interactions synchrones lorsqu’une requête et une réponse correspondante se produisent dans un laps de temps (c’est-à-dire, moins de deux minutes) et comme une seule transaction.

API de données

Les fonctions CRUD (création, lecture, mise à jour, suppression) sur les petits jeux de données (c’est-à-dire, moins de 1 Mo) sont idéalement adaptées en tant qu’API. Les requêtes sur les données de référence ou les jeux de données ouverts sont également d’excellents candidats. Les requêtes qui peuvent potentiellement renvoyer une grande quantité de données peuvent être mises en œuvre sous forme d’API, à condition que des techniques comme la pagination et la segmentation des données soient appliquées afin que les réponses ne soient pas tardives. Les tailles de message ou de pagination API appropriées dépendent du rendement général du réseau et des systèmes principaux de requête, ainsi que des valeurs de délai HTTP sur les systèmes consommateurs. En général, les messages API ne doivent pas dépasser 10 Mo dans le réseau organisationnel et doivent être limités à 1 Mo pour ceux consommés sur Internet. Les essais du rendement devraient être effectués pour ajuster les limites des messages et les tailles de pagination.

La création et la mise à jour de grandes quantités de données ne sont pas appropriées pour les API, pas plus que les scénarios où la création ou la mise à jour de données sont contraires à un modèle relationnel complexe où des problèmes d’intégrité peuvent provoquer l’échec de la transaction.

Par exemple, l’ajout de transactions de compte à mesure qu’elles se produisent est un bon cas d’utilisation pour une API. L’ajout d’une journée de transactions à un grand livre serait mieux effectué par un traitement par lots planifié. L’accès en lecture à des données précises est un cas d’utilisation courant, et on peut le voir dans de nombreuses offres de données ouvertes.

API transactionnelles synchrones

Les API ne doivent être utilisées pour effectuer une transaction que lorsqu’une réponse est attendue, idéalement en temps réel. Les API nécessitent en fin de compte que les systèmes de consommateur et de fournisseur soient disponibles pour que la transaction aboutisse et donnent lieu à une nouvelle tentative d’occupation ou à des boucles de sondage occupées lorsque le système de fournisseur est hors service. Les scénarios où une réponse n’est pas requise, comme les transactions de type incendie « fire-and-forget » (envoi et oubli) ou de type notification, doivent être mis en œuvre à l’aide d’une messagerie asynchrone au lieu des API. Cela permet à la transaction globale d’être plus résistante aux interruptions; ce qui est particulièrement important lorsque les systèmes de consommateur et de fournisseur sont gérés par diverses équipes ou organisations, ont des ententes de niveau de service différentes, ou résident dans des installations différentes.

Par exemple, lorsqu’une commande est validée dans le système financier et qu’une facture est retournée, une API fournit une réponse pour confirmer les renseignements sur la facture. Les données recueillies à partir de capteurs autonomes comme les capteurs météorologiques ne conviennent pas bien aux API. Les capteurs ne veulent pas attendre une confirmation que l’API a reçu les données. Ces capteurs doivent plutôt envoyer des messages asynchrones à un système de file d’attente. De cette façon, les capteurs peuvent continuer à fournir des données tandis que les services en aval peuvent consommer les données et les traiter à leur propre vitesse.

API transactionnelles asynchrones

Les API peuvent encore être utilisées lorsque la réponse n’est pas en temps réel (p. ex., flux de travail, processus de longue durée, intervention manuelle). Dans les cas où une réponse ne peut pas se produire dans un délai HTTP et où la charge transactionnelle globale est relativement faible (p. ex., quelques transactions par seconde), une API de rappel ou un Webhook doit être mis en œuvre par le système consommateur. Les API de rappel ou les Webhooks donnent au fournisseur d’API un point d’extrémité pour renvoyer la réponse une fois la transaction terminée. Les points d’extrémité statiques où l’adresse URL de rappel ou Webhook est définie comme une configuration pour chaque consommateur d’API doivent être mis en œuvre pour les API protégées. Cela évite le risque d’attaques par interception pour acheminer la réponse vers un point d’extrémité non autorisé. Les points d’extrémité dynamiques par lesquels le consommateur d’API passe l’adresse URL de rappel ou Webhook comme partie du message de requête peuvent être utilisés pour les API où les systèmes consommateurs sont nombreux et en constante évolution, et où les données sont publiques ou à faible risque (p. ex., Données ouvertes).

Un exemple d’une telle transaction de longue durée serait une requête complexe qui recherche plusieurs jeux de données sur plusieurs champs. Cette requête peut être soumise à une API et recevoir un Webhook pour surveiller la réponse finale.

Les transactions asynchrones à volume élevé (c’est-à-dire, des centaines ou des milliers par seconde) (p. ex., traitement des paiements par carte de crédit, suivi des médias sociaux) doivent être mises en œuvre au moyen de files d’attente de messages de demande et de réponse, qui sont mieux conçues pour gérer les scénarios de débit élevé. Dans ces scénarios, la file d’attente de réponses est surveillée pour les messages contenant un identifiant précisé pour désigner la réponse pour une demande précédente.

API organisationnelles

Exposer la fonctionnalité d’un système opérationnel en tant qu’API est l’un des moyens les plus puissants de créer des processus opérationnels plus intégrés et de favoriser les économies numériques. Tout processus opérationnel qui peut être déclenché par un autre système est un bon candidat d’API. Une API pour déclencher le processus avec les entrées obligatoires comme le schéma de demande est un bon point de départ.

Un bon exemple de systèmes opérationnels est les réclamations. Une réclamation peut être présentée par une API, démarrant l’activité de traitement de cette réclamation. La présentation de l’API peut créer un enregistrement et envoyer un avis à un agent de réclamation selon lequel il doit commencer le processus. Peut-être faut-il envoyer des inspecteurs pour évaluer la validité de la réclamation. Cette approche ouvre également la voie à une automatisation future, permettant à l’API de faire appel à d’autres services. On peut consulter un estimateur tiers avant même qu’un agent de réclamations ouvre le fichier.

API techniques et d’utilitaire

Les API peuvent être déployées simplement pour fournir des points de découplage dans un système donné. Il s’agit en fait du cas d’utilisation le plus courant et constitue la base de la plupart des solutions d’informatique en nuage. Chaque fois qu’une catégorie ou une entité peut être appelée à partir d’un système distant (p. ex., une autre machine virtuelle, un conteneur, un serveur) ou même une autre application fonctionnant sur le même système, elle pourrait bénéficier d’une exposition en tant qu’API. La contrepartie consiste à évaluer l’effort supplémentaire d’élaboration et de maintenance de l’API par rapport à la nécessité d’isoler un module d’application particulier et la possibilité de le déployer et de le mettre à l’échelle séparément du reste de l’application. L’architecture des microservices et l’architecture axée sur le service (AAS) reposent sur ce concept.

Ces API sont couramment utilisées dans les produits de PaaS (plateforme comme service) pour permettre l’intégration avec d’autres systèmes. La possibilité d’accéder aux fonctionnalités de plateforme au moyen de l’API permet aux organisations de connecter leurs systèmes existants sans devoir les reconstruire entièrement sur une nouvelle plateforme. Dans de nombreux cas, ces plateformes disposent de fonctionnalités permettant d’automatiser le mappage des schémas, éliminant ainsi la nécessité pour les systèmes existants de modifier leurs objets de requête ou de réponse afin de les harmoniser avec la nouvelle plateforme.

Portée de votre API

Déterminer le nombre de fonctionnalités à placer dans une API est un équilibre entre une complexité raisonnable et la réduction du nombre d’interactions pour accomplir quelque chose de valeur.

Concentration sur l’entité

L’approche la plus simple pour contrôler la complexité de l’API consiste à limiter la portée d’une API à un seul objet ou entité opérationnel (p. ex., client, installation, permis). Les principes REST permettent d’harmoniser avec une API sur une ressource, qui équivaut en gros à un seul objet ou entité opérationnel. Lors de la conception d’un nouveau système, l’application de méthodes de conception pilotées par un domaine est un moyen efficace d’identifier la bonne granularité et la portée des API.

Concentration sur le contrôle d’accès

Les mesures de contrôle d’accès et les autorisations sont plus facilement gérés au niveau de l’API plutôt que par niveau d’opération. Par conséquent, si une API a des profils de sécurité très différents (p. ex., un grand groupe de consommateurs avec lecture seule et un groupe beaucoup plus petit avec création/mise à jour/suppression), il serait préférable de mettre en œuvre des services distincts pour chaque profil de sécurité. Dans cet exemple, une API en lecture seule peut être déployée et accessible au moyen d’un autre segment de réseau et permettre un schéma d’authentification plus simple, tandis que la version plus privilégiée de l’API serait déployée dans un segment de réseau plus protégé et nécessiterait une authentification plus solide.

Concentration sur le contexte du consommateur

Les API, en particulier les API organisationnelles, peuvent souvent avoir des contextes d’exécution différents pour divers groupes de consommateurs. Par exemple, une API de gestion de compte peut offrir aux utilisateurs finaux la possibilité de gérer eux-mêmes les renseignements de profil tout en offrant aux utilisateurs administratifs la possibilité de gérer le contrôle d’accès et les privilèges système. Dans cet exemple, la fonctionnalité doit être divisée en une API utilisateur en libre-service et une API de gestion administrative des utilisateurs. Essayer de placer toute la logique conditionnelle dans une seule API la rendrait inutilement complexe, d’autant plus qu’il n’y a aucune possibilité qu’un seul processus opérationnel ait besoin d’interagir en même temps dans les deux contextes de consommation.

API composites

Les API composites agissent comme agrégateurs pour plusieurs API en aval. Ces API se trouvent généralement dans une architecture de microservice où les données et les fonctionnalités sont maintenues par des services plus petits. Les API composites peuvent être essentielles pour réduire la complexité lorsque l’entreprise a besoin de toucher plusieurs systèmes principaux différents. Ces API ne se limitent pas aux flux de travail ou aux moteurs d’orchestration. Ils rassemblent simplement les composants opérationnels et facilitent ce facteur de valeur : réutilisation. Tout comme pour une API conventionnelle, il est essentiel qu’une API composite soit ciblée dans sa portée et son approche. Un composite ne doit pas simplement masquer plusieurs schémas de données en un seul grand schéma. Au lieu de cela, les API composites doivent translater des tâches précises dans les zones individuelles en aval qu’elles touchent.

Par exemple, un utilisateur qui crée un compte en même temps que la soumission de sa première commande doit déclencher plusieurs services : un service de commande pour gérer le stock et lancer une expédition, un service de traitement des paiements et un service de création de compte. Un service composite reçoit la demande avec tous les renseignements fournis pour la commande et fait appel à ces services afin qu’ils exécutent chacun leurs fonctions désignées. Le service de commande retourne le numéro de confirmation de commande, le processeur de paiement traitement les renseignements de réception de paiement, et le service de création de compte confirme que le compte a été créé. Le service composite prend ensuite ces réponses et crée un modèle de données avec uniquement les renseignements qui doivent être retournés au client.

Redimensionnement et mise à l’échelle

Le partage et la réutilisation des API impliquent qu’elles doivent être conçues pour permettre l’augmentation de la capacité. Une API qui devient de plus en plus populaire peut se retrouver dans une situation où le rendement commence à se dégrader à mesure que de plus en plus de systèmes commencent à la consommer.

Dimensionnement initial

Il faut toujours établir une base de mesure du rendement pour toute API. Au minimum, une API partagée avec d’autres systèmes ou organisations doit être testée pour les paramètres suivants, jusqu’à concurrence du double (2x) au moins de l’utilisation maximale prévue au cours de la première année :

La limite supérieure du moment où l’API commence à échouer à la capacité d’infrastructure actuellement allouée doit également être établie en matière de débit et de concurrence.

Cet essai de charge doit être effectué dans le cadre d’un essai de système entier qui met la charge sur l’ensemble du système plutôt qu’une seule API pour être représentatif des scénarios de production. Les API techniques et utilitaires de base sont moins critiques, mais il faut tout de même procéder à des essais de charge globale du système afin de veiller à ce que les API ne créent pas de goulets d’étranglement sur le rendement.

Mise à l’échelle de la capacité

Les API bien construites doivent avoir relativement peu de code et ne pas nécessiter de capacité de calcul significative. Par conséquent, le facteur de contrainte pour la plupart des API est autour de la concurrence (p. ex., connexions réseau, fils) plutôt que de la capacité (p. ex., mémoire, processeur). Par conséquent, la mise à l’échelle horizontale en ajoutant plus de conteneurs ou de machines virtuelles est généralement plus efficace que l’allocation d’une capacité de calcul accrue. Il y a des scénarios où l’API est présentée comme faisant partie d’une application plus intégrée (p. ex., plateformes analytiques, LCPE), auquel cas l’API ne peut pas être mise à l’échelle indépendamment de l’application qu’elle expose.

Limitation et gestion de l’achalandage

Les plateformes de gestion des API et de passerelle doivent être déployées pour les API exposées aux consommateurs externes ou tiers. Toutes API partagées dans l’ensemble du GC ou à l’extérieur du GC doivent utiliser le magasin de l’API du GC à cette fin. Ces capacités fournissent des fonctionnalités de limitation des demandes et de gestion de l’achalandage; ce qui permet de limiter la concurrence et le débit écarte la nécessité d’adapter l’API tout en éliminant le risque de défaillance de l’API si la demande dépasse la capacité. La mise en garde à cette approche est qu’une fois les limites atteintes, les consommateurs commenceront à recevoir des messages d’échec ou de rejet, même si l’API réelle reste entièrement opérationnelle. Cela ne doit être utilisé que pour gérer contre une charge exceptionnelle et non pour remplacer une mise à l’échelle efficace de l’API.

Détails de la page

Date de modification :