System Account Requisition Process

Step 1: Request system access via form.

Step 2: Infoway will assess your request and either approve or request more information.

Step 3: Once approved, Infoway will notify you via email and provide instructions on how to retrieve your credentials (Client ID and Client Secret).

Step 4: Use your credentials to request a token using the Authentication Token URL.

Step 5: Use the token you received in step 4 to access the FHIR API.

Step 5a: Tokens expire every 30 mins, so repeat step 4 and 5 as often as you need.

API Endpoints

Get an Authorization Token

Your system user will be assigned a client ID and secret which can be used to request a token. This token is used in subsequent calls to the APIs for information.

Response

The access token below is used in subsequent calls as an Authorization HTTP Header.

FHIR API Request

After getting the authorization token from the response above, you can make subsequent calls to the FHIR API. Below is just a simple example to show how to include the authorization token as a HTTP Header. Please review the Postman Collection listed below for more examples.

Postman Collection

Postman is an online tool that helps to test and communicate with RESTful APIs. In order to make integration with the FHIR REST APIs easier, we have published a postman collection that can be used to authenticate, query, fetch and search the data on the Terminology Server. You must have appropriate access to be able to use some of the functions such as modifying data. Review the postman collection and use it as a template to get your own script of software application integrated with our APIs. You may be required to Fork the collection and save it under your own workspace in order to make any changes and send requests to the Terminology Server. We also have a GitHub repository with the Postman collection stored as a file which you can import into your own workspace. See details below.

Postman collection is here

GitHub Repository

You can also access the Postman collection from our GitHub repository. You can import the collection into your own Postman workspace and make any changes or modifications as you see fit. You can also send messages into the Terminology Server without needing to Fork the Collection.

[GitHub Repository] https://github.com/terminologystandardsservice/public

Fork a Collection

In order to use the collection, we have published, you must fork or copy the collection and bring it into your own workspace. You will require a Postman account which you can create for free, or have one for your company or organization. Once you have forked the collection, you can modify the requests and send requests to the Terminology Server. You will be able to view the responses on the bottom panel of the main screen.

• Login to Postman.
• Go to the postman collection here.
• Click on the Terminology Standards Service Collection and on the right side, click on Fork.
• Provide a fork label and a workspace name.
• Select the "Watch original collection" checkbox.
• Click Fork Collection.

Get Authorization Token in Postman

Before you can make any queries to the FHIR API, you must get an authorization token. You can either use your personal username and/or password for Terminology Server or a System account.

Personal Account

• Login to Postman.
• Navigate to the forked collection.
• Click on Terminology Standards Service Collection.
• Click on Authorization tab.
• If you are using Postman for Desktop, please add the following URL as the Callback URL.  https://oauth.pstmn.io/v1/browser-callback
• Click on Get new Access Token at the very bottom of the page.
• It will take you to the login page. 
• Enter your username and password to login. 
• You will get a popup saying you "Authentication Complete".
• Click Proceed. 
• Click on Use Token
• Now you can navigate to any of the examples and press the Send button to get a response from the Terminology Server.

System Account

• Process for using a system account is very similar to that of the personal account.
• Login to Postman.
• Navigate to the Forked Terminology Standards Service Collection.
• Click on the Authorization tab.
• Select Client Credentials under Grant Type.
• Enter the Client ID and Client Secret in the appropriate fields.
• Click on Get new Access Token.

Downloading Artifacts using Syndication API

Users can programmatically download files related to the various CodeSystems and ValueSets using the Syndication API. As of today, files that are available for download are SNOMED CT CA RF2 files, CCDD files and pCLOCD files. More files maybe added later. The URLs below are publicly accessible meaning you do not require any credentials to access them. They are XML formatted and contains a list of files available for download for each code system. To get started, please follow the ‘Syndication Download Instructions’ below. You will require system account credentials to download the files.

Syndication Download Instructions

This user guide will help you use the Syndication API to download the desired files. In this example, we use the SNOMED RF2 file.

The Syndication API URL is https://terminologystandardsservice.ca/syndication/alias/<feed-name>/syndication.xml.
The SNOMED RF2 Feed URL is https://terminologystandardsservice.ca/syndication/alias/production_snomed_rf2/syndication.xml.

Step-by-Step Instructions

1. Making an HTTP GET Request to the Syndication API.
   
   To retrieve the list of available files, use the following curl command:
   curl 'https://terminologystandardsservice.ca/syndication/alias/production_snomed_rf2/syndication.xml''
2. Understanding the API Response
   
   The response will be in XML format and will look something like this:
   
   
   Response

   <?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. Get a Token
   In order to download the file, you must get a token first. In order to get the token, you can call the authorization service with your Client ID and Client Secret. You must acquire these credentials using the system account access request form.
   

   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. Downloading the File
   To download the file, use the href property from the <link> element in the sample response in section 2. You will need to include a Bearer token for authorization.
   First, obtain a token using your client ID and secret described in the previous section. Then, use the token in the following curl command to save the output to a file:
   

   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

   Replace YOUR_ACCESS_TOKEN with the token you obtained and snomed_rf2_release.zip with your desired file name.

5. Verify the downloaded file
   

   From the XML response in section 2, you may use the ncts:sha256Hash property to verify the SHA256 checksum. Below are commands that can be used to generate the SHA256 hash locally on your machine and compare that to the one on the XML Response.

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

HL7 International Tools

HL7 international tools such as IG Publisher and Validator can now be integrated with our new Terminology Server.

How to Get Started

To begin, you will need to request an API key from Infoway, making it easy to configure HL7 tools (IG Publisher and Validator) for seamless terminology access. You will need to update the `fhir-settings.json` configuration file for the tool with the api key provided by Infoway. For more detailed instructions you can refer to HL7’s documentation. Infoway is also here to support you through the setup process if needed.

Supported Versions

• HL7 IG Publisher version 1.8.1 or later
• HL7 Validator version 6.5.0 or later

Note: Since this is a new configuration in the Infoway server and a recently introduced capability in the HL7 tooling, some adjustments may still be needed as we optimize. We welcome your feedback as we work to improve this functionality.

Accessing the Terminology Server APIs with an API Key

If your application does not support OAuth2 credentials (the preferred method), and you are using tools other than the HL7 tools mentioned above, then you can use an API Key to access the Terminology Server APIs as a final option. Follow these steps carefully, as the process differs from the OAuth2 flow.

1. Use the Dedicated API Key URL
   • To access the APIs using an API Key, use the following URL: https://terminologystandardsservice.ca/tx/fhir
   • Ensure that all API requests include the `/tx/fhir` context path before appending query parameters.
2. Include the API Key in the HTTP Header
   • The API Key must be provided as an HTTP header in your requests.
     Api-Key: <your-api-key>
3. Example CURL Command
   • Here is a sample CURL command to demonstrate how to make a request using the API Key:
     

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

Note

• Syndication API Access: Downloads through the Syndication API are not available for API Key users. Only FHIR Resources are available.
• Compatibility: Use API Keys only if your application does not support OAuth2.

Resources:

• System Access Request Form
• HL7 FHIR Rest API documentation
• Postman User Guide