Archivée [2020-03-31] - Directive sur la gestion des technologies de l'information

La technologie de l’information (TI) permet au gouvernement fédéral d’exécuter ses opérations et la transformation des services. La TI est essentielle, sur le plan stratégique, pour accroître la productivité et améliorer les services gouvernementaux au public pour le bienfait des citoyens, des entreprises, des contribuables et des employés.

Modification : 2019-08-02

Outils sous-jacents

Lignes directrices :

Norme :

Procédures obligatoires :

Hiérarchie

Directive sur la gestion des technologies de l'information

Voir la hiérarchie complète

Annexe D - Procédures obligatoires pour les interfaces de programmation d'applications

D.1 Date d'entrée en vigueur
- D.1.1Les présentes procédures entrent en vigueur le 1^er décembre 2018.
D.2 Procédures
- D.2.1Les présentes procédures contiennent les détails des exigences énoncées à la section 6 de la Directive sur la gestion de la technologie de l'information.
- D.2.2Voici les procédures obligatoires :
  - D.2.2.1Suivez les normes relatives au numérique du gouvernement du Canada – Les API doivent être développées en respectant les normes relatives au numérique du gouvernement du Canada, plus précisément :
    - D.2.2.1.1Concevez avec les utilisateurs en effectuant ce qui suit :
      - D.2.2.1.1.1Collaborez avec des développeurs qui sont censés utiliser votre API afin de veiller à ce que les spécifications de l'interface répondent à leurs besoins et tiennent compte de leurs contraintes ou limites.
      - D.2.2.1.1.2Élaborez des API 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.
    - D.2.2.1.2D.2.2.1.2 Permettez au personnel d'offrir de meilleurs services en effectuant ce qui suit :
      - D.2.2.1.2.1Veillez à 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 API.
      - D.2.2.1.2.2Adoptez des pratiques d'intégration et de prestation continues (CI/CD) et de développement axé sur les essais (DAE) 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.
    - D.2.2.1.3Travaillez de manière ouverte par défaut en effectuant ce qui suit :
      - D.2.2.1.3.1Élaborez des API qui peuvent être utilisées publiquement et permettre la réutilisation, lorsque vous travaillez avec des données de nature non délicates.
    - D.2.2.1.4Utilisez des normes et des solutions ouvertes en effectuant ce qui suit :
      - D.2.2.1.4.1Exposez les API 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.
      - D.2.2.1.4.2Tirez parti des outils et des cadres de sources ouvertes pour mettre en œuvre l'API dans la mesure du possible.
    - D.2.2.1.5Effectuez des itérations et des améliorations constantes en effectuant ce qui suit :
      - D.2.2.1.5.1Concevez des API en gardant à l'esprit la réutilisation, mais il ne faut pas prévoir ou deviner les besoins futurs.
      - D.2.2.1.5.2Veillez à ce que les API 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é.
  - D.2.2.2Élaborez des API en suivant le modèle de transfert d'état représentationnel (REST) par défaut. REST est effectivement la norme pour l'intégration avec les services d'informatique en nuage et est également la norme établie par la majorité des autres gouvernements ayant des programmes d'API bien établis. Suivez les pratiques exemplaires de l'industrie lors de la conception et l'élaboration de votre API REST en effectuant ce qui suit :
    - D.2.2.2.1Représentez les ressources sous forme de localisateurs de ressources uniformes (URL) en veillant à ce que les URL représentent les entités et les objets d'affaires, et non les opérations sur ces entités et objets (c'est-à-dire, éviter les verbes à l'intérieur de la chaîne URL).
    - D.2.2.2.2Utilisez la notation des objets du langage Java (JSON) et d'autres représentations fondées sur JSON (p. ex., JSON-LD) comme la structure de message dans la mesure du possible et appliquer les pratiques suivantes :
      - D.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 API d'ajouter d'autres clés de haut niveau à l'avenir.
      - D.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.
      - D.2.2.2.2.3Choisissez un seul cas de grammaire pour les clés d'objet, comme « soulignage » ou « casse de chameau », et l'utiliser de façon uniforme.
    - D.2.2.2.3Veillez à ce que chaque verbe représente une seule opération sur une ressource donnée et évitez d'utiliser des paramètres de demande pour exécuter d'autres opérations. Toutefois, voici les utilisations appropriées des verbes du protocole de transfert hypertexte (HTTP) dans le contexte d'une API 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).
    - D.2.2.2.4Utilisez des identificateurs de ressource uniformes (URI) pour identifier de façon unique des données qui sont retournées dans le cadre d'une réponse afin d'y exécuter des opérations futures, et les itérations peuvent tirer profit des ressources existantes avec une reprise minimale.
    - D.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 :
      - D.2.2.2.5.1Les en-têtes de demande ACCEPT (ACCEPTER) et CONTENT-TYPE (TYPE DE CONTENU) sont obligatoires.
      - D.2.2.2.5.2L'en-tête autorisation (AUTORISATION) est obligatoire pour les API sécurisées.
      - D.2.2.2.5.3On doit utiliser la touche de l'API dans l'en-tête plutôt que l'URI.
      - D.2.2.2.5.4On doit configurer les clés ou jetons d'API de façon sécuritaire et les utiliser de façon appropriée.
      - D.2.2.2.5.5La réponse doit contenir l'en-tête TYPE DE CONTENU.
    - D.2.2.2.5.6Publiez à l'aide des API du protocole simple d'accès aux objets (SOAP) ou du langage de balisage extensible (XML) 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).
  - D.2.2.3Veillez à ce que les API répondent avec des schémas de messages qui sont bien définis, faciles à comprendre, et à utiliser en appliquant les pratiques suivantes :
    - D.2.2.3.1Tirez parti des modèles d'information communs reconnus par l'industrie (p. ex., NIEM, RH-JSON, HL7) 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 prioritaire 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.
    - D.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 API de données ouvertes, de rapports et aux API statistiques seulement, et strictement interdite dans les API de données principales, transactionnelles ou commerciales. Les API doivent résumer la représentation des données physiques principales du consommateur.
    - D.2.2.3.3Évitez les structures de données relationnelles comme JSON et XML puisqu'elles 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'API.
    - D.2.2.3.4Veillez à 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'API au niveau du contrat.
    - D.2.2.3.5Évitez 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'API REST et conformez-vous aux défectuosités de la version 1.2 de SOAP (en anglais seulement) au moment de la création de l'API SOAP.
    - D.2.2.3.6Résumez 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'API 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.
    - D.2.2.3.7Veillez à ce que l'interaction entre le consommateur et le fournisseur de l'API 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'API (p. ex., réussite d'une séance d'identification). Toute interaction où de multiples API sont appelées dans une séquence reproductible pour créer une interaction commerciale unique doit être mise en œuvre comme une API détaillée afin d'éviter le fardeau de l'orchestration concernant le consommateur.
  - D.2.2.4Validez votre conception de l'API en l'utilisant avec une application de production au sein de votre organisation.
    - D.2.2.4.1Créez une fois pour plusieurs canaux en concevant des API 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'API, soit à une couche mandataire, sans qu'il soit nécessaire de créer d'autres API.
    - D.2.2.4.2Lancez un projet-pilote interne d'abord en élaborant des API parallèlement à un cas d'utilisation interne qui s'intégrerait dans l'API et utiliser ce projet-pilote interne pour valider la mise en œuvre de l'API avant de le publier aux fins d'utilisation externe.
  - D.2.2.5Assurez-vous de la sécurité de l'API lorsque l'on conçoit et met en œuvre une API qui donne accès à des données protégées ou privilégiées. Au moins, les pratiques de contrôle de sécurité suivantes doivent être suivies pour toute API autre que celles qui exposent des données publiques (p. ex., des données ouvertes).
    - D.2.2.5.1Appliquez les communications protégées en veillant à ce que les données de nature délicate ne soient jamais envoyées au moyen d'une connexion non sécurisée ou non chiffrée, et dans la mesure du possible, les données de nature non délicate doivent aussi être envoyées au moyen d'une connexion sécurisée. Activez le protocole TLS 1.2 ou des versions ultérieures, conformément aux directives du CST.
    - D.2.2.5.2Concevez des API pour résister aux attaques en veillant à ce que toutes les API soient conçues et mises en œuvre pour résister aux attaques courantes d'API comme les débordements de tampon et l'injection SQL. Traitez toutes les données présentées comme non fiables et validez-les avant le traitement. Tirer parti du schéma et des modèles de données pour veiller à la bonne validation des données.
    - D.2.2.5.3N'incluez pas des données de nature délicate dans les URL de demande puisque les chaînes d'URL peuvent être suivies et compromises, même avec un chiffrement de transport. Si une requête comporte des éléments de données de nature délicate (p. ex., le numéro d'assurance sociale), transmettez les paramètres de requête comme une charge utile de message JSON plutôt que dans la chaîne de demande d'URL.
    - D.2.2.5.4Protégez l'accès aux API en mettant en œuvre une stratégie de contrôle de l'accès qui protège les API d'un mauvais appel, y compris des références de fonction et de données non autorisées. Autorisez et authentifiez toujours avant toute opération pour veiller à ce que les API soient restreintes aux personnes ou aux systèmes autorisés. Utiliser des normes ouvertes comme OpenID Connect et Open Authorisation 2.0 (OAuth 2.0) pour les API REST, et le langage SAML 2.0 (Security Assertion Markup Language 2.0) pour les API SOAP. Veillez à ce que la clé ou le secret API soit bien protégé. Les API de données ouvertes doivent être sécurisées avec une clé API pour permettre le suivi de l'utilisation et fournir la capacité de déterminer et d'éviter des utilisations malveillantes. Les API de données ouvertes doivent être sécurisées avec une clé API pour permettre le suivi de l'utilisation et fournir la capacité de déterminer et d'éviter des utilisations malveillantes.
    - D.2.2.5.5Appliquez les pratiques sécuritaires en matière de gestion des jetons selon lesquelles l'authentification fondée sur le jeton est fortement recommandée et est obligatoire pour toutes API publiées d'être utilisées à l'échelle du gouvernement du Canada ou à l'extérieur. 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 API REST. WS-Security SAML Token Profile (en anglais seulement) est requis pour les API 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.
    - D.2.2.5.6Utilisez des passerelles et des données de substitution plutôt que des listes blanches lorsque vous exposez des API à 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 IP (protocole Internet) entrantes. La fonction de passerelle du magasin d'API peut être utilisée. Lorsque vous utilisez des API externes, la route passe par des mandataires (sortie) au lieu d'utiliser une liste blanche d'adresses IP sur le pare-feu sortant.
    - D.2.2.5.7Intégrez et automatisez les essais de sécurité pour valider tous nouveaux changements au code source de l'API et pour assurer la robustesse des changements demandés. Évaluez l'incidence du changement et effectuez des essais en conséquence. Des audits périodiques de l'accès de l'API peuvent être nécessaires, selon la nature des données et son utilisation.
    - D.2.2.5.8Vérifiez l'accès aux données de nature délicate selon lequel l'accès aux API traitant de données de nature délicate ou personnelle doit être consigné pour un audit ultérieur et examiné régulièrement. Les journaux d'accès doivent inclure au moins le système et les identificateurs individuels qui tentent d'accéder à l'API ainsi que l'horodatage.
    - D.2.2.5.9Consignez et surveillez le rendement et l'activité en faisant le suivi de l'utilisation et en surveillant les activités suspectes anormales y compris les profils d'accès comme les demandes après les heures normales, les demandes de données volumineuses, entre autres. Utilisez les normes de consignation (p. ex., format d'événement commun) et intégrez les journaux de façon centralisée. Déterminez les dépendances et surveillez les vulnérabilités, surtout celles pour les exécutions téléchargées qui fonctionnent dans le cadre de l'API. Les événements suspects doivent être envoyés à la capacité ou à l'autorité appropriée des opérations de sécurité conformément aux politiques sur la cybersécurité du gouvernement du Canada et au Plan de gestion des événements de cybersécurité du gouvernement du Canada.
  - D.2.2.6Utilisez un encodage et des métadonnées uniformes afin de veiller à ce que les API soient interopérables dans les organisations et à ce que vous mainteniez l'uniformité des données en mettant en œuvre les pratiques suivantes à la définition de l'API :
    - D.2.2.6.1Utilisez Unicode Transformation Format-8 (UTF-8) comme étant le type de codage standard pour tous les textes et toutes les représentations textuelles des données par API. Ce processus doit être respecté pour toutes les API publiées à l'échelle du GC et à l'externe. D'autres codages peuvent être utilisés à des fins uniques et/ou dans des API intraorganisationnelles seulement, s'il y a des limites techniques à l'utilisation de UTF-8.
    - D.2.2.6.2Utilisez le format de date uniforme de l'Organisation internationale de normalisation 8601 (ISO 8601), en temps universel coordonné (UTC), comme le format de date et heure standard pour les champs de données et d'horodatage dans les API 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 <yyyy-mm-dd>T<hh:mm:ss>Z. Toute autre représentation du temps dans le système source doit être convertie à ce format par l'API.
    - D.2.2.6.3Appuyez les langues officielles de sorte que tout le contenu en français ou en anglais retourné comme données doit être imbriqué avec les codes de langue BCP-47 utilisés comme des touches, en particulier « fr » et « en ». Les API externes doivent répondre avec du contenu dans la langue demandée si les données principales l'appuient. Les API 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.
  - D.2.2.7Améliorez et appuyez l'API tout au long de son cycle de vie en effectuant ce qui suit :
    - D.2.2.7.1Créez de façon itérative en lançant de nouvelles versions de l'API à mesure que les exigences changent ou que de nouvelles exigences sont introduites. Sollicitez activement la rétroaction des consommateurs de l'API pour comprendre si l'API offre une valeur appropriée et apportez des modifications dans les itérations futures.
      - D.2.2.7.1.1Modifiez chaque changement à l'API aussi petit soit-il, en suivant la structure de création de versions v<Majeur>.<Mineur>.<Correctif> suivant la structure 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'API.
        
        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.
      - D.2.2.7.1.2L'URL doit être le reflet de la version principale seulement (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'API à 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 le contrat, la documentation de l'interface, et le message de réponse.
    - D.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) afin de veiller à ce que les systèmes consommateurs aient le temps de migrer vers la dernière version de l'API. 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.
    - D.2.2.7.3Publiez un point de contact désigné à toutes les équipes qui utilisent votre API dans le magasin d'API. Si l'API 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 API de très grande criticité.
    - D.2.2.7.4Chaque API doit être accompagnée d'un accord sur les niveaux de service (ANS) 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.)
  - D.2.2.8Mesurez et publiez les références de l'API selon lesquelles l'API doit faire 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 :
    - D.2.2.8.1Exécutez des essais du rendement et de charge sur l'API 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'API 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 CI/CD automatisé afin de veiller à ce qu'ils soient effectués sur chaque nouvelle version.
    - D.2.2.8.2Les sommaires du 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'API et l'accord sur les niveaux de service (ANS). Cette information doit être mise à jour pour chaque version.
    - D.2.2.8.3Le rendement de l'exécution doit faire l'objet d'un suivi et d'établissement de rapports afin de cerner les tendances et de veiller à ce que l'API ait la capacité nécessaire pour répondre à la demande d'utilisation.
    - D.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'ANS é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'API s'effondrer.
  - D.2.2.9Utilisez et concevez des API raisonnablement en reconnaissant que les API ne sont pas la solution à tous les scénarios d'intégration. Il faut tenir compte des suivants lorsqu'on décide de mettre en œuvre une API 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 :
    - D.2.2.9.1Les API fondées sur la recherche (modèle de traction) sont préférables aux API fondées sur les collecteurs de données (modèle de poussée). Le fait que les systèmes utilisateurs interrogent les API 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 API 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 API. Les techniques et outils d'intégration de données en lots doivent être utilisés pour les modèles de synchronisation de données et seulement lorsque cela est absolument nécessaire.
    - D.2.2.9.2Limitez l'utilisation des interrogations avec des caractères de remplacement dans les API puisqu'ils peuvent être dangereux 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.
    - D.2.2.9.3Les API 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 API 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.
    - D.2.2.9.4La capacité d'injecter des chaînes ou des objets de requête définis par le consommateur dans une API doit être limitée aux API de données ouvertes, de rapports et de statistiques seulement, et strictement interdite dans les API 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 API. 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'API 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 API internes d'une organisation.
    - D.2.2.9.5Appliquez des considérations spéciales pour les jeux de données en lots puisqu'il y aura des scénarios où les API devront contribuer à la mise à disposition des jeux de données en vrac entre les systèmes ou au public. Dans ces scénarios, il faut tenir compte des facteurs suivants :
      - D.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 API externes, car ils peuvent contourner les mécanismes de balayage de contenu malveillant.
      - D.2.2.9.5.2Une API 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.
      - D.2.2.9.5.3Si le jeu de données est publié sur des serveurs de fichiers déjà disponibles pour le consommateur, une API pourrait être mise en œuvre pour retourner un lien vers un fichier particulier en fonction de paramètres de demande particuliers.
  - D.2.2.10Les API doivent être publiées pour être trouvables. On doit documenter clairement la façon dont chaque API doit être utilisée. La documentation doit être concise et à jour. Les pratiques suivantes doivent être respectées afin de veiller à ce que les API soient documentées de façon appropriée sans que le fardeau de la gestion des documents d'accompagnement soit trop lourd :
    - D.2.2.10.1Toutes les API doivent être publiées dans le magasin de l'API aux fins de la découverte et de la gestion du cycle de vie. Les API doivent être convenablement étiquetées pour indiquer si elles sont pour l'utilisation intraministérielle, interne du gouvernement du Canada, ou publique.
    - D.2.2.10.2Utilisation OpenAPI, une spécification d'interface lisible par machine pour les API REST, pour consigner les contrats d'API 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.
    - D.2.2.10.3Chaque API SOAP doit être accompagnée d'un contrat de langage de description de services Web (WSDL). Le WSDL est une spécification lisible par machine qui permet au développeur du consommateur de l'API de générer le code du consommateur.
    - D.2.2.10.4Publiez les essais unitaires et les données d'essai comme la façon la plus efficace de consigner ce qu'une API doit faire, accompagnés du contrat de l'API. Cela devient plus facile si la méthodologie de TDD a été suivie au cours de l'élaboration de l'API.
    - D.2.2.10.5Évitez les documents d'accompagnement volumineux. La nécessité d'un grand document distinct expliquant chaque méthode et chaque attribut indique habituellement que l'API est trop volumineuse, générique ou complexe. Envisagez de diviser l'API en composantes plus petites et de limiter la structure des messages.

Signaler un problème ou une erreur sur cette page

Date de modification :: 2017-08-25

Recherche et menus

Recherche

Archivée [2020-03-31] - Directive sur la gestion des technologies de l'information

Outils sous-jacents

Hiérarchie

Archives

Annexe D - Procédures obligatoires pour les interfaces de programmation d'applications