Processus de demande – compte de système

Étape 1 : Remplissez le formulaire de demande d’accès par un système.

Étape 2 : Inforoute évaluera votre demande et l’approuvera ou vous demandera plus d’information..

Étape 3 : Une fois la demande approuvée, Inforoute vous enverra, par courriel, la marche à suivre pour récupérer vos données d’accès (identifiant et authentifiant de client).

Étape 4 : Suivez l’URL pour le jeton d’authentification et utilisez vos données d’accès pour obtenir un jeton.

Étape 5 : Utilisez le jeton reçu à l’étape 4 pour accéder à l’API FHIR.

Étape 5a : Les jetons expirent toutes les 30 minutes. Répétez les étapes 4 et 5 aussi souvent que nécessaire.

Points terminaux d’API

Obtenir un jeton d’authentification

L’utilisateur du système recevra un identifiant et un authentifiant qui lui permettront d’obtenir un jeton d’authentification (ou d’accès). Il utilisera ensuite ce jeton pour faire des appels d’API afin d’obtenir de l’information.

Réponse

Le jeton dans l’exemple ci-dessous sera utilisé dans les appels comme en-tête de requête HTTP Authorization.

Requête à l’API FHIR

Une fois le jeton obtenu, vous pouvez faire des appels à l’API FHIR. Un exemple simple d’intégration du jeton comme en-tête de requête HTTP figure ci-dessous. Voir la collection sur Postman mentionnée ci-dessous pour obtenir d’autres exemples.

Dépôt GitHub

Vous pouvez accéder à la collection Postman à partir de notre dépôt GitHub et l’importer dans votre espace de travail personnel sur Postman afin d’y apporter les modifications souhaitées. Vous pouvez aussi envoyer des requêtes au serveur terminologique sans devoir créer un embranchement à la collection.

[Dépôt GitHub] https://github.com/terminologystandardsservice/public

Collection Postman

Postman est un outil en ligne qui vous aidera à mettre à l’essai des API RESTful et à établir des communications avec celles-ci. Nous y avons créé une collection pour faciliter l’intégration aux API REST FHIR. Vous pouvez vous en servir pour authentifier, interroger, récupérer ou chercher des données sur le serveur terminologique. Certaines fonctionnalités, comme la modification des données, sont réservées aux personnes possédant un certain type d’accès. Consultez la collection, et utilisez les modèles pour concevoir le script de votre application logicielle qui s’intègre à nos API. Vous devrez peut-être créer un embranchement à la collection et sauvegarder le tout dans votre espace de travail pour pouvoir effectuer des changements et envoyer des requêtes au serveur terminologique. Il existe aussi un dépôt GitHub contenant la collection Postman sous forme de fichier à importer dans votre espace de travail. Voir les détails ci-dessous.

La collection Postman se trouve ici.

Créer un embranchement à une collection

Pour pouvoir utiliser notre collection, vous devez créer un embranchement ou la copier dans votre propre espace de travail. Vous aurez à créer un compte Postman gratuit pour vous ou pour votre entreprise ou organisation. Une fois l’embranchement créé, vous pourrez modifier les requêtes et les envoyer au serveur terminologique. Vous verrez les réponses s’afficher dans la zone située au bas de l’écran principal.

• Connectez-vous à Postman.
• Allez dans les collections, qui se trouvent ici.
• Cliquez sur la collection ontoserver.canada puis, dans la section de droite, cliquez sur Fork.
• Attribuez un nom à votre embranchement, et choisissez un espace de travail.
• Cochez la case Watch original collection.
• Cliquez sur le bouton Fork Collection.

Obtenir un jeton d’authentification dans Postman

Avant de pouvoir interroger l’API FHIR, vous devez obtenir un jeton d’authentification (ou d’accès). Vous pouvez utiliser votre nom d’utilisateur et votre mot de passe pour le serveur terminologique, ou utiliser une connexion de système.

Compte personnel

• La marche à suivre pour utiliser un compte de système ressemble à celle utilisée avec un compte personnel.
• Connectez-vous à Postman.
• Rendez-vous à la collection créée à partir d’un embranchement.
• Cliquez sur Terminology Standards Service Collection.
• Cliquez sur l’onglet Authorization.
• Tout au bas de la page, cliquez sur le bouton Get new Access Token.
• Vous arriverez à la page de connexion.
• Entrez votre nom d’utilisateur et votre mot de passe.
• Une fenêtre avec le message Authentication complete s’affichera.
• Cliquez sur Proceed.
• Cliquez sur Use Token.
• Vous pouvez maintenant naviguer d’un exemple à l’autre et utiliser le bouton Send pour obtenir une réponse du serveur terminologique.

Compte de système

• La marche à suivre pour utiliser un compte de système ressemble à celle utilisée avec un compte personnel.
• Connectez-vous à Postman.
• Rendez-vous à la collection créée à partir d’un embranchement Terminology Standards Service Collection.
• Cliquez sur l’onglet Authorization.
• Sous Grant type, sélectionnez Client Credentials.
• Entrez l’identifiant et l’authentifiant de client dans les champs appropriés.
• Cliquez sur le bouton Get new Access Token.

Télécharger des artéfacts à l’aide d’une API de syndication

Les utilisateurs peuvent télécharger par programmation des fichiers liés aux divers systèmes de codes (CodeSystems) et ensembles de valeurs (ValueSets) à l’aide d’une API de syndication. Pour l’instant, les fichiers RF2 de l’édition canadienne de SNOMED CT, les fichiers du RCM et les fichiers pCLOCD peuvent être téléchargés – d’autres pourraient s’ajouter dans l’avenir. Les URL fournies ci-dessous sont accessibles à tous; vous n’aurez pas à entrer de données d’accès. Elles mènent à une liste, en format XML, de fichiers téléchargeables pour chaque système de code. Pour commencer à télécharger des artéfacts, suivez les instructions ci-dessous. Vous devrez entrer les données d’accès de votre compte de système pour télécharger des fichiers.

Instructions pour télécharger à l’aide de la syndication

Vous trouverez, dans le présent guide, de l’aide pour utiliser l’API de syndication pour télécharger les fichiers dont vous avez besoin. Aux fins de l’exemple, nous utilisons le fichier de SNOMED en format RF2.

L’URL de l’API de syndication est : is https://terminologystandardsservice.ca/syndication/alias/<feed-name>/syndication.xml.
L’URL du fil RF2 de SNOMED est : is https://terminologystandardsservice.ca/syndication/alias/production_snomed_rf2/syndication.xml.

Instructions

1. Envoyer une requête HTTP GET à l’API de syndication
   
   Pour obtenir la liste des fichiers disponibles, utilisez la commande cURL suivante :
   curl 'https://terminologystandardsservice.ca/syndication/alias/production_snomed_rf2/syndication.xml''
2. Comprendre la réponse de l’API
   
   La réponse est transmise en format XML et ressemble à ceci :
   
   
   Réponse

   <?xml version="1.0" encoding="UTF-8"?>
   <feed xmlns="http://www.w3.org/2005/Atom" xmlns:ncts="http://ns.electronichealth.net.au/ncts/syndication/asf/extensions/1.0.0" 
     xmlns:onto="http://ontoserver.csiro.au/syndication/">
     <title>initial-snomed_rf2</title>
     <link rel="alternate" href="https://terminologystandardsservice.ca/syndication/feed/20240831_001_SNOMED_RF2_RC/syndication.xml" />
     <subtitle />
     <id>urn:uuid:523dd9c5-3c05-47ab-aea1-61f476b989bf</id>
     <generator version="2.1.0">Atomio</generator>
     <updated>2024-08-29T15:43:00Z</updated>
     <ncts:atomSyndicationFormatProfile>http://ns.electronichealth.net.au/ncts/syndication/asf/profile/1.0.0</ncts:atomSyndicationFormatProfile>
     <entry>
       <title>Snomed RF2 Release 20240831</title>
       <link rel="alternate" type="application/zip" 
     href="https://terminologystandardsservice.ca/syndication/feed/20240831_001_SNOMED_RF2_RC/entry/74a84814-0e52-421b-b948-51d41ac2f7bc/artefact/e3d1a6d6a92301607d80e7889d4f9f363065be44a8dc92e645a4de8dbf335843.zip" length="690979420" 
       ncts:sha256Hash="e3d1a6d6a92301607d80e7889d4f9f363065be44a8dc92e645a4de8dbf335843" />
       <category term="RF2" label="RF2 ZIP package" scheme="http://ontoserver.csiro.au/syndication/rf2" />
       <id>urn:uuid:74a84814-0e52-421b-b948-51d41ac2f7bc</id>
       <updated>2024-08-29T15:43:00Z</updated>
       <published>2024-08-29T15:43:00Z</published>
       <summary>Snomed RF2 Release 20240831</summary>
       <ncts:contentItemIdentifier>http://snomed.info/sct</ncts:contentItemIdentifier>
       <ncts:contentItemVersion>http://snomed.info/sct/20611000087101/version/20240831</ncts:contentItemVersion>
     </entry>
   </feed>

3. Obtenir un jeton
   Pour pouvoir télécharger le fichier, vous devez d’abord obtenir un jeton. Pour ce faire, vous pouvez utiliser le service d’autorisation et fournir vos données d’accès uniques (identifiant et authentifiant de client). Vous pouvez obtenir ces données d’accès en utilisant le formulaire de demande d’accès – compte de système.
   

   curl --location --request POST 'https://terminologystandardsservice.ca/authorisation/auth/realms/terminology/protocol/openid-connect/token' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'client_id={{client_id}}' \
   --data-urlencode 'client_secret={{client_secret}}'

4. Télécharger le fichier
   Pour télécharger le fichier, utilisez l’attribut href de l’élément <link> de l’exemple de réponse donné à la section 2. Vous devrez inclure un jeton porteur pour obtenir l’autorisation.
   Obtenez d’abord un jeton à l’aide de vos données d’accès uniques comme décrit dans la section précédente. Utilisez ce jeton dans la commande cURL ci-dessous pour sauvegarder le contenu obtenu sous forme de fichier :
   

   curl 'https://terminologystandardsservice.ca/syndication/feed/20240831_001_SNOMED_RF2_RC/entry/74a84814-0e52-421b-b948-51d41ac2f7bc/artefact/e3d1a6d6a92301607d80e7889d4f9f363065be44a8dc92e645a4de8dbf335843.zip'
   -H 'Authorization: Bearer <your_access_token> -O snomed_rf2_release.zip

   Remplacez YOUR_ACCESS_TOKEN par le jeton que vous avez obtenu, et remplacez snomed_rf2_release.zip par le nom que vous souhaitez donner à votre fichier.

5. Vérifier le fichier téléchargé
   

   De la réponse en XML obtenue à la section 2, vous pouvez utiliser la propriété ncts:sha256Hash pour vérifier la somme de contrôle SHA256. Voici des commandes à utiliser pour générer la fonction SHA256 localement et faire la comparaison avec la réponse en XML obtenue.

   • Windows Commande Powershell
     Get-FileHash <file> -Algorithm SHA256
   • Commande Powershell
     sha256sum <file>
   • Commande MacOS
     shasum -a 256 <file>

Outils d’HL7 International

Notre nouveau serveur terminologique permet maintenant l’intégration d’outils d’HL7 International, comme l’outil de publication de guides d’implantation (IG Publisher) et l’outil de validation (Validator)

Par où commencer

Demandez d’abord à Inforoute de vous fournir une clé API, afin de faciliter la configuration des outils d’HL7 (IG Publisher et Validator) et l’accès à la terminologie. Vous devrez mettre à jour le fichier de configuration fhir-settings.json de l’outil en utilisant la clé API fournie par Inforoute. Pour plus d’information, voir la documentation d’HL7. Inforoute peut vous aider avec les réglages, au besoin.

Versions prises en charge

• HL7 IG Publisher : version 1.8.1 ou suivante
• HL7 Validator : version 6.5.0 ou suivante

Note: Il s’agit d’une nouvelle configuration sur le serveur d’Inforoute, et d’une fonctionnalité récemment offerte par HL7. Certains ajustements pourraient être requis, et nous vous invitons à nous faire part de vos commentaires pour nous aider à améliorer cette fonctionnalité.

Accéder aux API du serveur terminologique à l’aide d’une clé API

Si votre application ne prend pas en charge les données d’accès de type OAuth2 (la méthode privilégiée), et que vous utilisez des outils autres que les outils d’HL7 mentionnés ci-dessus, vous pouvez utiliser une clé API pour accéder aux API du serveur terminologique. Il s’agit d’une solution de dernier recours. Suivez bien les étapes ci-dessous; elles diffèrent de celles fournies pour les données de type OAuth2.

1. Utiliser l’URL réservée à la clé API
   • Pour accéder aux API à l’aide d’une clé API, utiliser l’URL suivante: https://terminologystandardsservice.ca/tx/fhir
   • S’assurer que toutes les demandes d’API incluent le chemin contextuel `/tx/fhir` avant d’ajouter les paramètres de configuration.
2. Inclure la clé API dans l’en-tête de requête HTTP
   • La clé API doit être fournie comme en-tête de requête HTTP dans vos requêtes. Api-Key: <your-api-key>
3. Exemple d’une commande cURL
   • Voici un exemple de commande cURL pour faire une requête à l’aide de la clé API :
     

     curl 'https://terminologystandardsservice.ca/tx/fhir' -H 'Api-Key: <your-api-key>'

Note

• Accès avec l’API de syndication: es utilisateurs de clé API n’ont pas accès aux téléchargements effectués à l’aide de l’API de syndication. Ils ont accès aux ressources FHIR seulement.
• Compatibilité: utilisez les clés API seulement si votre application ne prend pas en charge OAuth2.

Ressources

• Formulaire de demande d’accès de système
• Documentation sur l’API FHIR REST HL7
• Guide d’utilisation de Postman