Sélection de la langue

Gouvernement du Canada / Government of Canada

Recherche

Orientation sur l’élaboration des API pour le premier marché

Sur cette page

But

Le présent document traite du concept d’élaboration des API pour le premier marché et de la façon dont il permet d’élaborer des API solides et durables. L’approche du premier marché décrite ici permet de respecter les normes du gouvernement du Canada sur les interfaces de programmation d’applications (API), particulièrement dans les domaines suivants :

Premier marché ou code d’abord

Le processus d’élaboration des API est réparti en deux approches générales :

Premier marché – Commencez par définir le marché des API en fonction des exigences des consommateurs d’API. Le code est ensuite développé pour faire correspondre le contrat au système principal que l’API expose.

Code d’abord – Commencez par écrire le code de logique opérationnelle de l’exposition du système. Le marché des API est généré à partir du code à l’aide de divers outils d’élaboration logiciel.

Pourquoi le premier marché?

Le contrat des API définit la façon dont les consommateurs doivent interagir avec l’API. La définition précoce donne aux consommateurs d’API quelque chose de concret à concevoir et à développer tout en appliquant un niveau de découplage entre l’interface et le système principal.

Conception axée sur l’utilisateur pour les API

Les consommateurs d’API sont les utilisateurs des API. Si nous voulons appliquer une approche de conception axée sur l’utilisateur à l’élaboration des API, nous devrions considérer que le marché des API doit être dicté par les exigences des consommateurs d’API (c’est-à-dire, la façon dont les développeurs des systèmes consommateurs s’attendent à interagir avec l’API) plutôt que par la structure du système principal.

Par exemple, les consommateurs peuvent devoir vérifier l’adresse d’une personne, mais peuvent ne pas avoir l’autorisation de rechercher des adresses. Plutôt que de simplement fournir une recherche sécurisée dans des documents, une API pourrait avoir un point d’extrémité qui prend une adresse et un nom et retourne une simple réponse valide ou non valide.

Application du couplage faible

Le couplage faible des systèmes n’est pas réalisé simplement parce que nous déployons des API. En concevant le marché des API d’abord en fonction des besoins des consommateurs d’API, il force la logique opérationnelle dans l’API à découpler l’interface du système principal. La séparation de la conception du marché de la logique opérationnelle élimine toute possibilité d’insérer accidentellement des éléments étroitement couplés (p. ex., les structures des données brutes ou relationnelles, interactions avec état).

Par exemple, en maintenant les systèmes client et de commande étroitement couplés, la recherche d’un état de commande ne doit pas nécessiter l’extraction des détails sur le client ou des renseignements de facturation. Dans ce cas, les demandes d’état de commande peuvent rester rapides puisqu’elles isolent les données nécessaires et sont plus sécurisées, parce qu’elles n’autorisent pas accidentellement l’accès à des renseignements sensibles.

Développement parallèle

Les API et les systèmes consommateurs sont développés et itérés en parallèle. La coordination du changement entre plusieurs équipes techniques peut devenir extrêmement complexe. L’établissement d’un marché ferme avec des règles strictes de contrôle du changement est le seul moyen pratique de permettre un développement parallèle. Le marché des API sert de point commun d’uniformité entre les équipes. La définition d’un marché d’API permet d’abord de déployer des mécanismes comme des maquettes d’API et des services virtualisés, ce qui permet ensuite de développer et de tester des systèmes consommateurs sans que l’API réelle soit disponible.

Cet aspect est particulièrement utile lorsque l’on travaille simultanément sur plusieurs intégrations. Par exemple, le développement en parallèle lors de l’intégration avec plusieurs options de processeur de paiement permet de saisir et de communiquer les renseignements appropriés afin de répondre à toutes les exigences du processeur.

Détermination précoce des écarts de conception

De nombreux systèmes ne sont pas conçus à l’origine pour une intégration facile. Alors qu’une API peut être facilement exposée, la capacité de mapper et d’indexer systématiquement les données au moyen des systèmes externes peut être insuffisante. Les équipes de projet tiennent souvent pour acquis que leurs interactions sont la norme par défaut pour aborder un sujet, et peuvent ignorer le besoin d’autres formats qui sont nécessaires pour d’autres consommateurs.

Par exemple, un répertoire de personnel qui n’utilise pas un identificateur global unique (GUID) ou un numéro d’identification d’utilisateur (UID) pour chaque enregistrement peut être accessible en lecture seule, mais il n’existe en fait aucun moyen fiable de mettre à jour un enregistrement au moyen d’une API, car il n’existe aucun moyen cohérent d’identifier une personne donnée de manière unique. En commençant par le marché, on veillera à ce que ces écarts et ces limites soient déterminés au cours de la phase de conception. La génération du marché à partir du code entraîne souvent la découverte de ces limitations lors des essais et du déploiement, ce qui rend la résolution beaucoup plus difficile et coûteuse.

Qu’est-ce qui pose problème au sujet du premier marché?

Les divers avantages du développement des API pour le premier marché sont assortis de frais généraux et de compromis. À tout le moins, cela prend plus de temps et exige plus de discipline qu’une approche du code d’abord. Même si ces défis doivent être relevés, ils sont gérables et ne doivent pas être utilisés comme raisons pour éviter le développement des API pour le premier marché. Répondre à ces défis aide les équipes à devenir plus mûres dans la fourniture de logiciels modernes de façon évolutive et agile et ne sont pas uniques au développement des API.

Définition du schéma

La définition du marché exige généralement de définir le schéma de données à partir de rien. Alors que l’approche du code d’abord génère le schéma à partir des divers modèles d’objet et d’entité dans la logique opérationnelle des API, l’approche du premier marché est en fait une page vide. Les organisations qui adoptent l’approche du premier marché doivent investir dans la formation et le perfectionnement des compétences sur le sujet de la conception des données et des schémas d’interface.

La production d’une définition de schéma exige une connaissance approfondie du domaine et une compréhension des exigences opérationnelles. Plutôt que de considérer ce processus comme un obstacle, approchez-le comme une occasion pour entamer des affaires et le développement simultanément afin de veiller à ce que chacun travaille aux mêmes fins. Ces pratiques permettront de veiller à ce que la valeur réelle soit le résultat d’un projet.

Complexité accrue du code

Le couplage faible signifie que le code des API doit effectuer des opérations plus complexes en matière de mappage, de translation et de transformation des données. Un marché qui n’est pas une représentation directe de la structure des données principales signifie simplement qu’il y aura plus de codes à écrire dans l’API, ce qui augmente l’effort et le temps d’élaboration.

Afin de gérer la complexité du code, il est important d’utiliser des outils et des pratiques comme l’intégration continue et le déploiement continu (IC/DC) pour les essais automatisés et d’acceptation, ainsi que des examens de code et des programmes par les pairs pour obtenir un code de haute qualité. L’émergence de ces pratiques dans le développement de logiciels modernes est directement liée à la création d’équipes d’élaboration plus solides et plus qualifiées.

La gestion des versions est obligatoire

Un marché n’est utile que si les changements sont strictement contrôlés. L’équipe d’élaboration des API doit mettre en œuvre une version appropriée du marché des API, et toute modification du marché doit être clairement communiquée aux équipes des différents systèmes consommateurs. Des processus de contrôle de version et de communication doivent être établis et convenus entre les équipes d’élaboration des API et les équipes de consommateurs.

La gestion des versions est essentielle dans les solutions du premier marché ou du code d’abord. Le défaut d’autoriser le contrôle des versions dans les solutions de code d’abord entraîne souvent une complexité accrue au fil du temps ou des marchés accidentels rompus. L’approche du premier marché place la gestion de version à l’avant-garde de l’amélioration continue et assure le succès à long terme d’une API.

Tests répétitifs et automatisés

Les tests sont essentiels lorsque les équipes élaborent des composants de système en parallèle. Les tests permettent d’établir des références fonctionnelles et de rendement et doivent servir de preuve d’uniformité par rapport au marché des API. Les marchés à eux seuls ne peuvent pas représenter entièrement la fonctionnalité complète d’une API donnée, car ils ne décrivent pas la logique opérationnelle ou des choses comme la validation de données. Des tests reproductibles doivent être écrits dès le début, qui fournissent une couverture suffisante de la portée fonctionnelle de l’API pour donner aux consommateurs d’API un niveau élevé de confiance que l’API fonctionne comme prévu. Ces tests doivent ensuite être automatisés et exécutés sur chaque version de code API. Idéalement, ces scénarios de test seraient également utilisés pour générer des maquettes ou modules de remplacement d’API qui retournent des réponses dynamiques afin que les tests des systèmes consommateurs puissent se produire avant même que le développement de l’API soit terminé.

Utilisés conjointement avec les pipelines IC/DC, les tests automatisés deviennent la première ligne de validation du nouveau code. Le développement du premier marché permet aux développeurs de cerner des problèmes dans leur exécution avant qu’elle ne passe à d’autres, finit dans les tests d’acceptation, ou même potentiellement la production. Ces outils permettent aux développeurs de résoudre les problèmes tôt, avant qu’ils aient la chance d’avoir une incidence sur le projet. L’automatisation des tests entraîne également la réutilisation de scénarios de test et la mise en commun d’actifs numériques (p. ex., tests unitaires, scripts de test, données de test) qui peuvent être publiés. Cela permet aux consommateurs et aux fournisseurs d’API d’effectuer des tests à la fois par rapport à une base de référence uniforme comme des mécanismes de contrôle et de contrepoids continus au fur et à mesure que les changements sont déployés.

Quand ne pas utiliser le premier marché?

Comme pour tous les concepts technologiques, l’approche de premier marché n’est pas une solution miracle universelle pour développer des API. Il y a des scénarios où la valeur de l’approche du premier marché n’est pas justifiée par les frais généraux supplémentaires ou quand elle n’est tout simplement pas possible.

API d’utilitaire interne

Les API ne sont pas seulement utilisées pour exposer des fonctionnalités aux systèmes externes. Les API sont souvent utilisées pour simplement découpler les composants de code à l’intérieur d’un système afin de fournir une souplesse en matière d’évolutivité ou d’extensibilité future. Lorsqu’une API est simplement utilisée comme une abstraction interne et que le code API et le code de tous les composants consommateurs sont gérés par la même équipe ou même le développeur, l’approche du code d’abord peut être plus appropriée pour fournir des fonctionnalités plus rapidement.

Avant de désigner une API « à usage interne seulement », on doit effectuer une analyse appropriée pour déterminer la situation. Il est recommandé de consulter les groupes opérationnels adjacents afin de veiller à ce qu’ils n’aient pas ou n’aient pas besoin d’avoir accès à l’API. Ce qui est considéré seulement comme interne aujourd’hui pourrait être partagé demain.

Science des données et analyses

Les API exposant des jeux de données statistiques ou volumineux pour des applications de science des données ou d’analyses sont très différentes des API intégrées. Ces types d’API doivent offrir une souplesse et un rendement maximal et ne doivent pas interférer avec la représentation des données. Les concepts typiques de définition des marchés d’API ne s’appliquent pas vraiment ici. Les données géospatiales entrent également dans cette catégorie.

Limites des SaaS et des LCPE

La définition des marchés d’API peut tout simplement ne pas être possible lorsqu’on travaille avec des SaaS (logiciels comme service) et des logiciels commerciaux prêts à l’emploi (LCPE). Les logiciels de fournisseurs sont souvent fournis avec des API prêtes à l’emploi ou générées, et il y a très peu de possibilités de les configurer ou de les personnaliser. Si les API fournies par le fournisseur sont trop mal définies ou peuvent changer fréquemment en raison de petits changements dans la configuration des SaaS/LCPE, il est recommandé d’envisager de placer un proxy API intégré devant ces API où un marché plus stable peut être défini et converti vers les API fournies par le fournisseur. Lors de l’élaboration de ces proxys API, il est préférable de travailler avec l’approche du premier marché, car elle garantit que l’effort fournira un marché solide à l’extérieur de ces solutions.

Détails de la page

Date de modification :