Normes du gouvernement du Canada sur les API

1. Observer les normes du gouvernement du Canada relatives au numérique

Les API doivent être élaborées conformément aux normes relatives au numérique du gouvernement du Canada. Il faut porter une attention particulière aux points suivants :

• Conception avec les utilisateurs – Collaborez 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. Les API doivent être élaborées en fonction des exigences opérationnelles que les systèmes consommateurs sont sensés appuyer et non pas les structures de données principales auxquelles ils ont accès.
• Habilitez le personnel à offrir de meilleurs services – Veillez à 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. Les équipes doivent viser à adopter des pratiques d’intégration et de livraison continues (CI/CD) et de développement basé sur les tests (TDD) appuyées par des outils d’automatisation et des tests de sécurité intégrés. Cela constitue la base de l’adoption de DevOps à mesure que la maturité s’améliore.
• Travaillez dans un environnement ouvert par défaut – Lorsque vous travaillez avec des données non sensibles, construisez des API qui peuvent être utilisées publiquement et permettez la réutilisation.
• Utilisez des normes et des solutions ouvertes – Les API doivent être exposées au moyen de normes ouvertes acceptées par l’industrie, tandis que les protocoles privés des fournisseurs et les schémas de données doivent être évités. Nous vous encourageons à tirer parti des outils et des cadres de sources ouvertes pour mettre en œuvre votre API.
• Apportez des itérations et des améliorations fréquemment – Concevez les API en gardant à l’esprit la réutilisation, mais il ne faut pas prévoir ou deviner les besoins futurs. Veillez à 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é.

2. Concevoir des API REST solides

Les API doivent suivre 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 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 (en anglais seulement) de l’industrie lors de la conception et de l’élaboration de votre API REST.

• Représentez les ressources sous forme d’URL – Les localisateurs de ressources uniformes (URL) doivent représenter 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).
• Utilisez JSON – Utilisez la notation des objets du langage Java (JSON – en anglais seulement) et d’autres représentations utilisant le format JSON (p. ex., JSON-LD) comme structure de message dans la mesure du possible et appliquez les pratiques suivantes :
  • Formez 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.
  • É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.
  • Utilisez une grammaire uniforme pour les touches d’objet. Choisissez le soulignage ou « CamelCase » (Casse de chameau) et soyez cohérent.
• Évitez de surcharger les verbes – Chaque verbe doit représenter une seule opération sur une ressource donnée. Évitez d’utiliser les paramètres de la demande pour effectuer des opérations supplémentaires. 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
• Utilisez un URI pour déterminer les données de réponse – Si les données sont retournées dans le cadre d’une réponse, utilisez des identificateurs de ressources uniformes (URI) pour déterminer les données de façon unique afin qu’elles puissent être exploitées à l’avenir dans les opérations. De même, les premières versions peuvent s’inspirer des ressources existantes avec un minimum de reprises.
• Utilisez des en-têtes HTTP – La négociation de contenu devrait se faire à l’aide de l’approche axée sur les agents au moyen des en-têtes HTTP :
  • Les en-têtes de demande ACCEPT (ACCEPTER) et CONTENT-TYPE (TYPE DE CONTENU) sont obligatoires.
  • L’en-tête autorisation (AUTORISATION) est obligatoire pour les API sécurisées.
  • On doit utiliser la clef de l’API dans l’en-tête plutôt que l’URI.
  • Les clés/jetons de l’API doivent être correctement configurés et utilisés de manière appropriée.
  • La réponse doit contenir l’en-tête TYPE DE CONTENU.
• Utilisez le protocole SOAP seulement si cela est absolument nécessaire – Il est acceptable de publier 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).

3. Concevoir des schémas de messages bien définis et faciles à utiliser

Les API doivent fournir une réponse à l’aide de schémas de message faciles à comprendre et à utiliser. Les pratiques suivantes doivent être appliquées :

• Utilisez des modèles d’information communs – Tirez 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 relatives aux données du gouvernement du Canada.
• Évitez la structure des données brutes – L’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 abstraire la représentation physique des données des systèmes de support du consommateur.
• Évitez les structures de données relationnelles – JSON et XML 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.
• Évitez les schémas génériques ou ouverts – Les contraintes d’un schéma de données doivent être é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.
• Évitez les codes d’erreur normalisés – É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 à  SOAP 1.2 Fault (en anglais seulement) au moment de la création de l’API SOAP.
• Résumé des détails techniques internes – 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.
• Mettez en œuvre des interactions sans état – L’interaction entre le consommateur et le fournisseur de l’API doit être 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.

4. Utiliser les API créées

La meilleure façon de valider votre conception de l’API est de l’utiliser avec une application de production au sein de votre organisation.

• Créez une fois pour plusieurs canaux – Les API doivent être conçues de manière à pouvoir ê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.
• Effectuez d’abord un projet-pilote à l’interne – Créez des API en parallèle avec un scénario d’utilisation interne qui serait intégré à l’API. Utilisez ce projet-pilote interne pour valider la mise en œuvre de l’API avant de la publier pour utilisation externe.

5. Sécuriser l’API

La sécurité doit être au premier plan 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. Les pratiques suivantes doivent être suivies pour toute API autre que celles qui exposent des données publiques (p. ex., des données ouvertes). Il est important de noter que ces pratiques doivent fournir un ensemble des mesures de sécurité de base. D’autres mesures (p. ex., le chiffrement au niveau du message, l’authentification mutuelle et les signatures numériques) peuvent être requises en fonction du niveau de sensibilité des données.

• Veillez à ce que vos communications soient sécurisées – Utilisez toujours une connexion sécurisée ou chiffrée pour envoyer des données sensibles. Si possible, utilisez aussi une connexion sécurisée pour envoyer des données non sensibles.  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).
• Concevez des API résistantes aux attaques – Toutes les API doivent être conçues et mises en place de façon à résister aux attaques courantes des API telles que les surcharges de la mémoire tampon et les attaques par 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.
• Évitez d’insérer des données sensibles dans les URL de requête – Les chaînes d’URL de requête peuvent être retracées et compromises même avec le chiffrement du transport. Si une requête comporte des éléments de données sensibles (p. ex., numéro d’assurance sociale), 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.
• Protégez l’accès aux API – Mettez en place un système de contrôle d’accès qui protège les API contre l’utilisation abusive, les fonctions et les références de données non autorisées. Veillez à ce que les personnes et/ou systèmes soient toujours authentifiés avant d’effectuer toute opération afin de veiller à ce que l’accès aux API soit limité aux personnes et/ou systèmes autorisé(e)s. Utilisez des normes ouvertes, telles que OpenID Connect et Open Authorization 2.0 (OAuth 2.0) pour les API RESTful et le standard Security Assertion Markup Language 2.0 (SAML 2.0) pour les API SOAP. Assurez-vous que la clé/le code secret de l’API sont correctement protégés. Les API de données ouvertes doivent être sécurisées à l’aide d’une clé API pour permettre le suivi de l’utilisation, mais aussi pour permettre d’identifier et de prévenir toute utilisation malveillante potentielle.
• Appliquez des pratiques sécurisées en matière de gestion des jetons – L’authentification fondée sur les jetons est fortement recommandée et est obligatoire pour toute API publiée qui doit être utilisée dans l’ensemble du gouvernement du Canada et/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 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.
• Utiliser la passerelle et les « proxies » au lieu 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 de protocole Internet (IP) entrant. La fonction de passerelle de l’API Store peut être utilisée à cet effet. 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.
• Intégrez les tests de sécurité – Automatisez les tests de sécurité pour valider toute nouvelle modification du code source de l’API et garantir la robustesse des modifications demandées. Évaluez l’impact du changement et effectuez les tests nécessaires.
• Vérifiez l’accès aux données de nature délicate – L’accès aux API traitant de données de nature délicate et/ou personnelles doit être consigné pour vérification ultérieure 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. Des audits périodiques de l'accès à l'API peuvent être nécessaires en fonction de la nature des données et de leur utilisation.
• Enregistrez et surveillez les performances et activités – Suivez l’utilisation et surveiller les activités suspectes, y compris les modèles d’accès anormaux, tels que les demandes en dehors des heures d’ouverture, les demandes de données importantes et 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 les 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’API. 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.

6. Utiliser un codage et des métadonnées uniformes

L’uniformité des métadonnées et du codage assure l’interopérabilité des API entre les organisations et aide à maintenir l’uniformité des données. Les pratiques suivantes doivent être suivies lors de la définition de votre API :

• Utilisez Unicode pour le codage – Unicode Transformation Format-8 (UTF-8 – en anglais seulement) est 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.
• Utilisez un format de date uniforme – L’Organisation internationale de normalisation 8601 (ISO 8601 – en anglais seulement), en temps universel coordonné (UTC – en anglais seulement), est 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 <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’API.
• Appuyez les langues officielles – Tout le contenu en français ou en anglais retourné comme données doit être imbriqué avec les codes de langue BCP-47 (en anglais seulement) 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.

7. Faire progresser et appuyer l’API tout au long de son cycle de vie

Les API changeront au fil du temps en fonction de l’évolution des besoins du système et des utilisateurs. Ce changement doit être adéquatement appuyé et géré au moyen des pratiques suivantes :

• Créez de façon itérative – Élaborez et diffusez de nouvelles versions de l’API de façon itérative à mesure que les exigences changent et/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.
• Établissez des versions des API – Vous devez établir la version de chaque API. Toute modification à une API, aussi petite soit-elle, doit être indiquée au moyen d’une nouvelle version. Suivez la structure de contrôle des versions <Majeur>. <Mineur>. <Rustine> dans 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.
  • Rustine = 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.

  L’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’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 la documentation du contrat,  de l’interface et message de réponse.

• Respectez les dépendances actuelles des consommateurs – Appuyez au moins une version principale précédente (N-1, p. ex) 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.
• Fournissez un point de contact – Publiez un point de contact désigné à toutes les équipes qui utilisent votre API vers l’API Store. 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 très critiques.
• Définissez un ANS dès le départ – Chaque 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.)

8. Mesurer et publier les points de repère de l’API

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 :

• Effectuez un test de charge de l’API – Exécutez des essais de rendement 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.
• Mesurez et publiez les points de repère sur le rendement – Les 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’API et l’ANS. Cette information doit être mise à jour pour chaque version.
• Surveillez le rendement – Le 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’API ait la capacité nécessaire pour répondre à la demande d’utilisation.
• Effectuez un ralentissement artificiel à l’égard de l’ANS – Des 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.

9. Utiliser et concevoir les API de façon raisonnable

Les API ne sont pas la panacée pour tous les scénarios d’intégration. Il faut être prudent 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. On doit prendre en considération ce qui suit :

• Préférez les API de recherche aux collecteurs de données – Les 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. 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.
• Limitez les interrogations avec des caractères de remplacement – Les interrogations avec des caractères de remplacement dans les API peuvent être dangereuses du point de vue du rendement des données. Si les caractères de remplacement sont permis, assurez-vous qu’il y a 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.
• Segmentez les données sur les réponses pour les interrogations importantes – Les 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.
• Limitez les requêtes dynamiques ou ouvertes – La capacité d’injecter des chaînes ou des objets d’interrogation définis par le consommateur dans une API 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 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.
• Appliquez des considérations spéciales pour les jeux de données en vrac – Il y aura des scénarios où les API 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 :
  • petits jeux de données – Les 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éclencher l’API – Une 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.
  • rechercher et lier l’API – Si 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.

10. Publier et documenter l’API

Les API doivent être publiées de façon à ce qu’on puisse les trouver. On doit documenter clairement la façon dont chaque API doit être utilisée. La documentation doit être concise et à jour. Les pratiques suivantes aident à 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 :

• Publiez les API dans l'API Store – Toutes les API doivent être publiées dans l’API Store à des fins de recherche (pour qu’on puisse les retrouver) et de gestion du cycle de vie. Les API 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).
• Utilisez OpenAPI pour REST – OpenAPI (en anglais seulement) est une spécification d’interface lisible par machine pour les 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.
• Publiez un langage de description de services Web (WSDL) bien construits pour SOAP – Chaque API 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’API de générer le code du consommateur.
• Publiez les essais unitaires et les données d’essai – La façon la plus efficace de documenter ce qu’une API 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’API. Cela devient plus facile si la méthodologie de TDD a été suivie au cours de l’élaboration de l’API.
• É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’API est trop vaste, générique ou complexe. Envisagez de diviser l’API en composantes plus petites et de limiter la structure des messages.