Directive sur les services et le numérique - Annexe B : Procédures obligatoires sur les interfaces de programmation d’applications

Modification : 2019-08-02

Renseignements supplémentaires

Directive :

Hiérarchie

Version imprimable XML

Annexe B. Procédures obligatoires sur les interfaces de programmation d'applications

B.1 Date d'entrée en vigueur

  • B.1.1Les présentes procédures entrent en vigueur le 1er décembre 2018.

B.2 Procédures

  • B.2.1Les présentes procédures précisent les exigences énoncées à la section A.2.3.10.3 des Procédures obligatoires pour l'Examen de l'architecture intégrée.
  • B.2.2Voici les procédures obligatoires :
    • B.2.2.1Suivre les normes relatives au numérique du gouvernement du Canada – Les IPA doivent être élaborées conformément aux normes relatives au numérique du gouvernement du Canada, plus particulièrement :
      • B.2.2.1.1Concevoir avec les utilisateurs comme suit :
        • B.2.2.1.1.1Collaborer avec des développeurs qui sont censés utiliser votre IPA afin de veiller à ce que les spécifications de l'interface répondent à leurs besoins et tiennent compte de leurs contraintes ou limites.
        • B.2.2.1.1.2Élaborer des IPA en fonction des exigences opérationnelles que les systèmes consommateurs sont censés appuyer et non pas les structures de données principales auxquelles ils ont accès.
      • B.2.2.1.2Habiliter le personnel à offrir de meilleurs services en :
        • B.2.2.1.2.1Veiller à ce que les outils, la formation et les processus nécessaires soient en place pour appuyer un processus robuste et souple d'élaboration et de gestion du cycle de vie des IPA.
        • B.2.2.1.2.2Adopter des pratiques d'intégration et de livraison continues (CI/CD) et de développement basées sur les tests (TDD) appuyées par des outils d'automatisation, et des essais de sécurité intégrés. Cela constitue la base de l'adoption de DevOps à mesure que la maturité s'améliore.
      • B.2.2.1.3Travailler ouvertement par défaut comme suit :
        • B.2.2.1.3.1Élaborer des IPA qui peuvent être utilisées publiquement et permettre la réutilisation lorsque vous travaillez avec des données non sensibles.
      • B.2.2.1.4 Utiliser des normes et des solutions ouvertes par défaut en :
        • B.2.2.1.4.1Exposer les IPA au moyen de normes ouvertes acceptées par l'industrie, tandis que les protocoles prioritaires des fournisseurs et les schémas de données doivent être évités.
        • B.2.2.1.4.2Tirer parti des outils et des cadres de sources ouvertes pour mettre en œuvre l'IPA, dans la mesure du possible.
      • B.2.2.1.5Effectuer des itérations et des améliorations constantes comme suit :
        • B.2.2.1.5.1Concevoir les IPA en gardant à l'esprit la réutilisation, mais il ne faut pas prévoir ou deviner les besoins futurs.
        • B.2.2.1.5.2Veillez à ce que les IPA soient conçues de manière à permettre des itérations à mesure que de nouvelles exigences et de nouveaux cas d'utilisation apparaissent, tout en offrant un niveau raisonnable de rétrocompatibilité.
    • B.2.2.2Élaborer les IPA en suivant le modèle Representational State Transfer (REST) (en anglais seulement) par défaut. REST est effectivement la norme pour l'intégration avec les services infonuagiques et est également la norme établie par la majorité des autres gouvernements ayant des programmes d'IPA bien établis. Suivre les pratiques exemplaires de l'industrie lors de la conception et de l'élaboration de votre IPA REST comme suit :
      • B.2.2.2.1Représenter les ressources sous forme de localisateurs de ressources uniformes (URL) en veillant à ce qu'ils représentent les entités et les objets d'affaires, et non pas les opérations sur ces entités et objets (c'est-à-dire, éviter les verbes à l'intérieur de la chaîne URL).
      • B.2.2.2.2Utiliser la notation des objets du langage Java (JSON – en anglais seulement) et d'autres représentations fondées sur le langage JSON comme structure de message dans la mesure du possible et appliquer les pratiques suivantes :
        • B.2.2.2.2.1Formez les réponses comme un objet JSON et non comme un tableau. Les tableaux peuvent limiter la capacité d'inclure des métadonnées sur les résultats et limiter la capacité des IPA d'ajouter d'autres clés de haut niveau à l'avenir.
        • B.2.2.2.2.2Éviter les touches d'objet imprévisibles (c'est-à-dire, dynamiques) comme celles qui découlent des données, car cela ajoute une certaine friction pour les clients.
        • B.2.2.2.2.3Choisir une grammaire uniforme simple pour les clés d'objet, comme le « soulignage » ou la « CamelCase » (Casse de chameau) et l'utiliser de façon uniforme.
      • B.2.2.2.3Veiller à ce que chaque verbe représente une seule opération sur une ressource donnée et éviter d'utiliser des paramètres de demande pour passer d'autres opérations. Toutefois, voici les utilisations appropriées des verbes du protocole de transfert hypertexte (HTTP) dans le contexte d'une IPA REST : GET (OBTENIR) (extraire ou interroger une ressource),
        POST (AFFICHER) (créer une nouvelle ressource ou lancer une action),
        PUT (METTRE) (mettre à jour ou remplacer une ressource existante),
        DELETE (SUPPRIMER) (supprimer une ressource).
      • B.2.2.2.4Utilisez des identificateurs de ressources uniformes (URI) pour déterminer de façon unique les données qui sont retournées dans le cadre d'une réponse afin que les opérations puissent y être exploitées à l'avenir, et que des répétitions puissent exploiter les ressources existantes avec un minimum de reprises.
      • B.2.2.2.5La négociation de contenu doit se faire à l'aide de l'approche axée sur les agents au moyen des en-têtes HTTP, y compris :
        • B.2.2.2.5.1Les en-têtes de demande ACCEPT (ACCEPTER) et CONTENT-TYPE (TYPE DE CONTENU) sont obligatoires.
        • B.2.2.2.5.2L'en-tête autorisation (AUTORISATION) est obligatoire pour les IPA sécurisées.
        • B.2.2.2.5.3On doit utiliser la clef de l'IPA dans l'en-tête plutôt que l'URI.
        • B.2.2.2.5.4Les clés/jetons de l'IPA doivent être correctement configurés et utilisés de manière appropriée.
        • B.2.2.2.5.5La réponse doit contenir l'en-tête CONTENT-TYPE.
        • B.2.2.2.5.6Publier à l'aide des IPA du protocole simple d'accès aux objets (SOAP) ou du langage de balisage extensible (XML) seulement s'il y a des contraintes techniques du côté du fournisseur ou du consommateur. Tous les points d'extrémité de SOAP doivent respecter les spécifications de la version 1.2 de SOAP (en anglais seulement) et être conformes à la version 2.0 du WS-I Basic Profile (en anglais seulement).
    • B.2.2.3Veiller à ce que les IPA répondent à l'aide de schémas de message bien définis et faciles à comprendre, en appliquant les pratiques suivantes :
      • B.2.2.3.1Tirer parti des modèles d'information communs reconnus par l'industrie (p. ex., NIEM, RH-JSON, HL7 – en anglais seulement) dans la mesure du possible. Si vous devez définir votre propre modèle d'information, créez un modèle qui est neutre sur le plan de la technologie et de la plateforme plutôt que de simplement réutiliser un schéma privé du fournisseur. L'utilisation appropriée des modèles d'information communs doit respecter les normes en matière de données du gouvernement du Canada.
      • B.2.2.3.2L'exposition des structures de données brutes (p. ex., les ensembles de rangées, les ensembles de tableaux, LDAP DN) des systèmes principaux doit être limitée aux IPA de données ouvertes, de rapports et aux IPA statistiques seulement, et strictement interdite dans les IPA de données principales, transactionnelles ou commerciales. Les IPA doivent abstraire la représentation physique des données des systèmes de support du consommateur.
      • B.2.2.3.3Éviter les structures de données relationnelles comme JSON et XML puisqu'ils sont des structures de données hiérarchiques qui ne conviennent pas bien à la représentation des données relationnelles. Les schémas de données relationnelles doivent être écrasés en fonction du point de vue du consommateur de l'IPA.
      • B.2.2.3.4Veiller à ce que les contraintes d'un schéma de données soient évidentes lors de la lecture de la définition du schéma. Les structures de données génériques comme les paires clé-valeur et les champs génériques sont interdites en raison de l'incapacité de tester la compatibilité de l'IPA au niveau du contrat.
      • B.2.2.3.5Éviter de créer des codes d'erreur et des schémas personnalisés qui exigent une analyse approfondie par le système de consommation. Conformez-vous aux codes d'état HTTP (en anglais seulement) au moment de la construction de l'IPA REST et conformez-vous à SOAP 1.2 Fault (en anglais seulement) au moment de la création de l'IPA SOAP.
      • B.2.2.3.6Résumer des détails techniques internes selon lesquels les réponses, y compris les messages d'erreur, doivent résumer les détails techniques dans lesquels le consommateur de l'IPA n'a aucune visibilité. Les erreurs techniques internes, les listes des unités d'exécution et les identificateurs de processus, entre autres, doivent tous être tenus à l'écart des données de réponse.
      • B.2.2.3.7Veiller à ce que l'interaction entre le consommateur et le fournisseur de l'IPA soit sans état. On ne doit s'attendre à aucun concept de séance ou de gestion de l'état de la part du consommateur en ce qui a trait à l'IPA (p. ex., réussite d'une séance d'identification). Toute interaction où de multiples IPA sont appelées dans une séquence reproductible pour créer une interaction commerciale unique doit être mise en œuvre comme une IPA détaillée afin d'éviter le fardeau de l'orchestration concernant le consommateur.
    • B.2.2.4Valider votre conception de l'IPA en l'utilisant avec une application de production au sein de votre organisation.
      • B.2.2.4.1Créez une fois pour plusieurs canaux en concevant des IPA afin qu'elles puissent être utilisées par les systèmes internes du gouvernement du Canada, les partenaires de confiance et les parties externes (c'est-à-dire, le public). La conception doit permettre d'appliquer différents profils d'accès aux données, soit à l'IPA, soit à une couche mandataire, sans qu'il soit nécessaire de créer d'autres IPA.
      • B.2.2.4.2Menez un projet pilote à l'interne d'abord en concevant des IPA en parallèle avec un cas d'utilisation interne qui intégrerait à l'IPA et utiliser ce projet pilote interne pour valider la mise en œuvre de l'IPA avant de la diffuser pour usage externe.
    • B.2.2.5Assurer la sécurité de l'IPA lorsque l'on conçoit et met en œuvre une IPA qui donne accès à des données protégées ou privilégiées. À titre de base de référence minimale, les pratiques suivantes de contrôle de la sécurité doivent être suivies pour toute IPA autre que celles qui exposent des données publiques (p. ex., des données ouvertes).
      • B.2.2.5.1Appliquez les communications sécurisées en veillant à ce que les données de nature délicate ne soient jamais envoyées au moyen d'une connexion non sécuritaire ou non chiffrée, et dans la mesure du possible, les données non délicates devraient aussi être envoyées au moyen d'une connexion sécurisée. Activez la version TLS 1.2 ou les versions ultérieures, conformément aux lignes directrices du Centre de la sécurité des télécommunications (CST).
      • B.2.2.5.2Concevez des IPA qui résistent aux attaques en veillant à ce que toutes les IPA soient conçues et mises en œuvre pour résister aux attaques communes d'lPA comme les dépassements de mémoire tampon et l'injection SQL. Traitez toutes les données soumises comme non fiables et validez-les avant de les traiter. Exploitez les schémas et les modèles de données pour assurer la validation correcte des données.
      • B.2.2.5.3Ne pas inclure des données délicates dans les URL de demande puisque les chaînes URL peuvent faire l'objet d'un suivi et être compromises même avec le chiffrement du transport. Si une requête comporte des éléments de données sensibles (numéro d'assurance sociale, par exemple), définissez les paramètres de requête comme une charge de message JSON plutôt que dans la chaîne de requête URL.
      • B.2.2.5.4Protégez l'accès aux IPA en mettant en œuvre un système de contrôle de l'accès qui empêche la mauvaise innovation des IPA, y compris les références non autorisées aux fonctions et aux données. Assurez-vous toujours de vous authentifier et d'avoir ou donner les autorisations nécessaires avant toute opération pour limiter l'accès aux IPA aux personnes et/ou aux systèmes autorisés. Utilisez des normes ouvertes, telles que OpenID Connect et Open Authorization 2.0 (OAuth 2.0) pour les IPA RESTful et le standard Security Assertion Markup Language 2.0 (SAML 2.0) pour les IPA SOAP. Assurez-vous que la clé/le code secret de l'IPA sont correctement protégés. Les IPA de données ouvertes doivent être sécurisées à l'aide d'une clé IPA pour permettre le suivi de l'utilisation, mais aussi pour permettre d'identifier et de prévenir toute utilisation malveillante potentielle. Les IPA de données ouvertes doivent être sécurisées à l'aide d'une clé IPA pour permettre le suivi de l'utilisation, mais aussi pour permettre d'identifier et de prévenir toute utilisation malveillante potentielle.
      • B.2.2.5.5Appliquez des pratiques sécurisées en matière de gestion des jetons selon lesquelles l'authentification fondée sur les jetons est fortement recommandée et est obligatoire pour toute IPA publiée qui doit être utilisée dans l'ensemble du gouvernement du Canada ou à l'externe. Utilisez des jetons standard de l'industrie; ne créez pas de jetons personnalisés; évitez d'utiliser des systèmes de jetons exclusifs aux fournisseurs. JSON Web Token (JWT) (en anglais seulement) est requis pour les interactions IPA REST. WS-Security SAML Token Profile (en anglais seulement) est requis pour les IPA SOAP. Tous les jetons d'accès doivent expirer dans un délai raisonnable (c'est-à-dire, moins de 24 heures). Dans le cas du SAML, l'expiration de l'assertion doit être fixée de façon à contrôler la période de validité de toute la séance d'authentification et d'autorisation.
      • B.2.2.5.6Utilisez des passerelles et des données de substitution plutôt que des listes blanches lorsque vous exposez des IPA à Internet. Utilisez une couche de passerelle sécurisée pour fournir un point de contrôle de sécurité au lieu de simplement envoyer une liste blanche d'adresses de protocole Internet (IP) entrant. La fonctionnalité de passerelle du magasin d'IPA peut servir. Lorsque vous utilisez des IPA externes, la route passe par des mandataires (sortie) au lieu d'utiliser une liste blanche d'adresses IP sur le pare-feu sortant.
      • B.2.2.5.7Intégrez et automatisez les tests de sécurité pour valider les nouveaux changements au code source de l'IPA et assurer la résistance des changements demandés. Évaluez l'impact du changement et effectuez les tests nécessaires. Des audits périodiques de l'accès à l'IPA peuvent être nécessaires en fonction de la nature des données et de leur utilisation.
      • B.2.2.5.8Vérifiez l'accès aux données de nature délicate, de sorte que l'accès aux IPA traitant de données de nature délicate et/ou personnelle doit être consigné pour vérification ultérieure et examiné de façon régulière. Les journaux d'accès doivent inclure au moins le système et les identificateurs individuels qui tentent d'accéder à l'IPA ainsi que l'horodatage.
      • B.2.2.5.9Consignez et surveillez le rendement et l'activité en faisant le suivi de l'utilisation et de la surveillance des activités suspectes anormales y compris des tendances d'accès anormal comme les demandes après les heures normales, les demandes de données volumineuses, entre autres. Utilisez des normes d'enregistrement dans les journaux (p. ex., format d'événement commun) et intégrez les journaux de manière centralisée. Relevez l»es dépendances et surveillez les vulnérabilités, en particulier celles des temps d'exécution téléchargés qui fonctionnent comme composante de l'IPA. Les événements suspects doivent être transmis à la fonction ou à l'autorité compétente en matière d'opérations de sécurité, conformément aux politiques du gouvernement du Canada en matière de cybersécurité et au Plan de gestion des événements de cybersécurité du gouvernement du Canada.
    • B.2.2.6Utilisez un encodage et des métadonnées uniformes afin de veiller à ce que les IPA soient interopérables dans l'ensemble des organismes et maintenir l'uniformité des données en mettant en œuvre les pratiques suivantes en définissant l'IPA :
      • B.2.2.6.1Utilisez l'Unicode Transformation Format-8 (UTF-8 – en anglais seulement) comme le type de codage standard pour tous les textes et toutes les représentations textuelles des données par IPA. Ce processus doit être respecté pour toutes les IPA publiées à l'échelle du GC et à l'externe. D'autres codages peuvent être utilisés à des fins uniques et/ou dans des IPA intraorganisationnelles seulement, s'il y a des limites techniques à l'utilisation de UTF-8.
      • B.2.2.6.2Utilisez un format de date uniforme de l'Organisation internationale de normalisation 8601 (ISO 8601 – en anglais seulement), en temps universel coordonné (UTC – en anglais seulement), comme le format de date et heure standard pour les champs de données et d'horodatage dans les IPA publiées dans l'ensemble du GC et à l'externe. Le format de la date est <aaaa-mm-jj> tandis que le format de l'horodatage est <aaaa-mm-jj>T<hh:mm:ss>Z. Toute autre représentation du temps dans le système source doit être convertie à ce format par l'IPA.
      • B.2.2.6.3Appuyez les langues officielles de sorte que tout le contenu en français ou en anglais retourné comme données soit imbriqué avec les codes de langue BCP-47 (en anglais seulement) utilisés comme des touches, en particulier « fr » et « en ». Les IPA externes doivent répondre avec du contenu dans la langue demandée si les données principales l'appuient. Les IPA doivent interpréter l'en-tête HTTP ACCEPT-LANGUAGE (ACCEPTER LA LANGUE) et rendre le contenu approprié. Si l'en-tête n'est pas établi, le contenu dans les deux langues doit apparaître. Dans le cas des données et des systèmes unilingues, il faut déployer tous les efforts possibles afin de veiller à ce que la langue soit bien indiquée dans le message de réponse.
    • B.2.2.7Améliorez et appuyez l'IPA tout au long de son cycle de vie en suivant les pratiques suivantes :
      • B.2.2.7.1Créez de façon itérative en diffusant de nouvelles versions de l'IPA à mesure que les exigences changent ou que de nouvelles exigences sont introduites. Sollicitez activement la rétroaction des consommateurs de l'IPA pour comprendre si l'IPA offre une valeur appropriée et apportez des modifications dans les itérations futures.
        • B.2.2.7.1.1Indiquez la version de chaque modification à une IPA, aussi petite soit-elle, en suivant la structure de version v<Majeur>.<Mineur>.<Correctif> selon laquelle : Majeur = Lancement important susceptible de rompre la rétrocompatibilité.
          Mineur = Ajout d'attributs facultatifs ou de nouvelles fonctionnalités qui sont rétrocompatibles, mais qui doivent être mises à l'essai.
          Correctif = Solution interne qui ne devrait pas avoir d'incidence sur le schéma et/ou le contrat de l'IPA.
          Par exemple, passer de la v1.1.0 à la v1.1.1 permettrait une simple mise à niveau déployé en place puisqu'il s'agit d'une rustine, tandis que passer de la v1.1.0 à la v2.0.0 serait une importante diffusion et exigerait que l'ancienne version soit conservée pendant que les consommateurs font l'essai de la nouvelle version et migrent vers cette dernière.
        • B.2.2.7.1.2L'URL ne doit refléter que la version principale (p. ex., v3). Les versions ne doivent pas être passées en paramètre ou dans l'en-tête de la demande pour forcer le consommateur de l'IPA à identifier explicitement la version et pour éviter de passer par défaut à une version incompatible. Les versions mineures et les versions de la rustine n'ont pas besoin d'être dans l'URL puisqu'elles ne doivent pas rompre la rétrocompatibilité, mais elles doivent être clairement identifiées dans la documentation du contrat, de l'interface et message de réponse.
      • B.2.2.7.2Respectez les dépendances actuelles des consommateurs en appuyant au moins une version principale précédente (c'est-à-dire, N-1) pendant plusieurs mois afin de veiller à ce que les systèmes consommateurs aient le temps de migrer vers la dernière version de l'IPA. Communiquez votre feuille de route de développement aux équipes de consommateurs et travaillez avec elles pour comprendre l'incidence de tout changement majeur. Établissez des politiques de dépréciation et des calendriers clairs dès le départ afin que les consommateurs comprennent combien de temps ils doivent passer à chaque nouveau lancement avant que l'ancienne version ne soit mise hors ligne. Coordonnez les essais nécessaires sur tous les lancements mineurs et majeurs.
      • B.2.2.7.3Publiez un point de contact désigné à toutes les équipes qui utilisent votre IPA dans le magasin des IPA. Si l'IPA est publiée pour une utilisation pangouvernementale ou externe, publiez un compte de courriel de soutien. Un numéro de téléphone doit également être fourni pour les IPA très critiques.
      • B.2.2.7.4Chaque IPA doit être accompagnée d'une entente sur les niveaux de service (ENS) clairement défini. À tout le moins, l'ANS doit définir ce qui suit : Heures de soutien (p. ex., 24 heures sur 24, de 9 h à 17 h, heures de bureau d'un océan à l'autre).
        Disponibilité du service (p. ex., 99 %).
        Temps de réponse du soutien (p. ex., dans l'heure, 24 heures, meilleur effort).
        Pannes prévues (p. ex., nuit, semaine, tous les deux dimanches en soirée).
        Limite du débit de traitement (p. ex., 100 demandes par seconde par consommateur).
        Limite de taille du message (p. ex., <1 Mo par demande).
    • B.2.2.8Mesurez et publiez les références de l'IPA de sorte que le rendement de l'IPA fasse l'objet d'une analyse comparative périodiquement afin de veiller à ce que le rendement et la capacité répondent continuellement aux besoins opérationnels actuels et prévus. Les mesures suivantes doivent être prises :
      • B.2.2.8.1Effectuez des essais de rendement et de charge sur l'IPA pour déterminer le temps de réponse et le débit de traitement pendant une charge raisonnable, ainsi que pour déterminer les seuils de rendement au-delà desquels l'IPA devient instable. Les essais de rendement doivent être intégrés au cycle de développement, de préférence par l'entremise d'un pipeline automatisé d'intégration continue et de déploiement continu (CI/CD) afin de veiller à ce qu'ils soient effectués sur chaque nouvelle version.
      • B.2.2.8.2Les sommaires de rendement (p. ex., le temps de réponse moyen et le débit de traitement associé, le débit de traitement maximal stable) doivent être publiés en même temps que le contrat de l'IPA et l'ENS. Cette information doit être mise à jour pour chaque version.
      • B.2.2.8.3Le rendement du délai d'exécution doit faire l'objet d'un suivi et de rapports afin de cerner les tendances et de veiller à ce que l'IPA ait la capacité nécessaire pour répondre à la demande d'utilisation.
      • B.2.2.8.4Des mécanismes de ralentissement artificiel doivent être mis en place pour contrôler le débit de traitement par rapport à l'ENS énoncé afin de prévenir les pics imprévus d'activité. Il vaut mieux rejeter les demandes qui dépassent les limites de débit de traitement prédéfinies que de laisser l'IPA s'effondrer.
    • B.2.2.9Utilisez et concevez des IPA raisonnablement en reconnaissant que les IPA ne sont pas la solution pour tous les scénarios d'intégration. Il faut tenir compte des suivants lorsqu'on décide de mettre en œuvre une IPA et de concevoir les types de demandes qui sont autorisés afin de veiller à ce que l'architecture d'intégration soit appropriée et durable :
      • B.2.2.9.1Les IPA fondées sur la recherche (modèle de traction) sont préférables aux IPA fondées sur les collecteurs de données (modèle de poussée). Le fait que les systèmes utilisateurs interrogent les IPA en fonction de paramètres précis garantit que seules les données requises dans le contexte d'un processus opérationnel ou d'une transaction sont transmises. Cette approche permet également de veiller à ce que l'accès aux données puisse être mieux contrôlé du point de vue de la sécurité. Les IPA des contrôleurs de données favorisent la synchronisation et la prolifération des données de masse, ce qui est l'antithèse de l'architecture axée sur les IPA. Nous devrions utiliser des techniques et des outils d'intégration des données en vrac pour les modèles de synchronisation des données et seulement en cas de nécessité absolue.
      • B.2.2.9.2Limitez l'utilisation des interrogations avec des caractères de remplacement dans les IPA puisqu'elles peuvent être dangereuses du point de vue du rendement des données. Si les caractères de remplacement sont permis, veillez à ce qu'il y ait des limites quant au nombre de paramètres qui peuvent comporter une entrée de caractère de remplacement afin d'empêcher les recherches de données de grande taille. Il est beaucoup plus sécuritaire de rejeter une recherche comportant trop de caractères de remplacement que de mettre fin à une séance en effectuant une recherche dans la base de données du système principal.
      • B.2.2.9.3

        Les IPA qui exposent de grands jeux de données doivent appuyer une certaine forme de segmentation des données. Voici quelques modèles courants de pagination ainsi que des cas d'utilisation appropriés :

        page et par page – Il est préférable de l'utiliser pour naviguer dans de grands jeux de données statiques (p. ex., des données de référence) où le même jeu de données est susceptible d'être retourné en raison de la même référence de page au fil du temps.

        décalage et limite – Il est préférable de l'utiliser pour les IPA dont les systèmes principaux sont fondés sur le langage d'interrogation structuré (SQL), où le décalage représente le curseur de données d'une colonne indexée donnée.

        depuis et limite – Il est préférable de l'utiliser pour les requêtes où le consommateur s'intéresse au delta, puisque la dernière requête et la structure de données du système principal sont indexées en fonction du temps.

      • B.2.2.9.4La capacité d'injecter des chaînes ou des objets d'interrogation définis par le consommateur dans une IPA doit être limitée aux IPA de données ouvertes, de rapports et aux IPA statistiques seulement, et strictement interdite dans les IPA de données de référence, transactionnelles ou commerciales. Les requêtes dynamiques et ouvertes créent des surfaces d'attaque dangereuses pour les IPA. Il est préférable d'investir plus d'efforts dans l'identification de tous les cas d'utilisation d'interrogation valides et de concevoir l'IPA pour y répondre spécifiquement. Le GraphQL peut être utilisé à des fins statistiques, analytiques et d'établissement de rapports, mais ne doit pas être utilisé pour appuyer les opérations opérationnelles. OData ne doit être utilisé que si le système principal comporte des limites techniques et seulement pour les IPA internes d'une organisation.
      • B.2.2.9.5Appliquez des considérations spéciales pour les jeux de données en vrac puisqu'il y aura des scénarios où les IPA devront contribuer à la mise à disposition de jeux de données en vrac entre les systèmes ou au public. Dans ces scénarios, il faut tenir compte des facteurs suivants :
        • B.2.2.9.5.1Les jeux de données plus petits doivent être retournés dans des formats comportant un faible temps système requis (p. ex., valeurs séparées par des virgules (CSV) ou JSON) plutôt que XML. Il faut éviter d'utiliser des fichiers joints comprimés, surtout lorsqu'on utilise des IPA externes, car ils peuvent contourner les mécanismes de balayage de contenu malveillant.
        • B.2.2.9.5.2Une IPA peut être mise en œuvre comme déclencheur pour lancer une interface hors bande (p. ex., transfert de fichiers géré) plus appropriée pour le déplacement de grands volumes de données.
        • B.2.2.9.5.3Si le jeu de données est publié sur des serveurs de fichiers déjà disponibles pour le consommateur, une IPA pourrait être mise en œuvre pour retourner un lien vers un fichier particulier en fonction de paramètres de demande particuliers.
    • B.2.2.10Les IPA doivent être publiées de façon à ce qu'on puisse les trouver. On doit documenter clairement la façon dont chaque IPA doit être utilisée. La documentation doit être concise et à jour. Les pratiques suivantes doivent être suivies afin de veiller à ce que les IPA soient documentées de façon appropriée sans que le fardeau de la gestion des documents d'accompagnement soit trop lourd :
      • B.2.2.10.1Toutes les IPA doivent être publiées dans le magasin des IPA aux fins de la découverte et de la gestion du cycle de vie. Les IPA doivent être identifiées de façon appropriée pour indiquer l'usage prévu (à l'échelon intraministériel, interne au gouvernement du Canada ou par le grand public).
      • B.2.2.10.2Utilisez OpenIPA, une spécification d'interface lisible par machine pour les IPA REST, pour consigner les contrats d'IPA REST. Il existe des outils à source ouverte (p. ex., Swagger – en anglais seulement) qui peuvent ensuite produire de la documentation lisible par l'humain à partir de cette spécification, ce qui évite la nécessité de créer et de maintenir une documentation distincte.
      • B.2.2.10.3Chaque IPA SOAP doit être accompagnée d'un contrat de langage de description de services Web (WSDL) en anglais seulement). Le WSDL est une spécification lisible par machine qui permet au développeur du consommateur de l'IPA de générer le code du consommateur.
      • B.2.2.10.4Publiez les essais unitaires et les données d'essai puisque la façon la plus efficace de documenter ce qu'une IPA est censée faire est de publier les cas d'essai et les données utilisées pour la valider en même temps que le contrat de l'IPA. Cela devient plus facile si la méthodologie de TDD a été suivie au cours de l'élaboration de l'IPA.
      • B.2.2.10.5Évitez les documents d'accompagnement lourds. La nécessité d'un grand document distinct expliquant chaque méthode et chaque attribut indique habituellement que l'IPA est trop vaste, générique ou complexe. Envisagez de diviser l'IPA en composantes plus petites et de limiter la structure des messages.
Date de modification :