Termhub in 5 Minutes Tutorial

This is an easy-to-use tutorial for accessing TermHub APIs through api.terminologyhub.com. TermHub is a cloud healthcare terminology server offering access to a large library of code systems, value sets, and concept mappings along with standard developer-friendly mechansims for interacting with that content (such as FHIR® terminology services).

Tutorial Training Video

Reference deployments

To test against our TermHub terminology servers, you must first create an account by signing up at https://app.terminologyhub.com/signup.

Table of Contents

1. Tutorials by Language
2. Use Cases
3. Maintenance Commands
4. Resources
5. Contributing
6. License

Tutorials by Language

• Click for Bash examples.
• Click for Curl examples.
• Click for Go examples.
• Click for FHIR examples.
• Click for Java examples.
• Click for JavaScript examples.
• Click for Postman examples.
• Click for Python examples.

Back to top

Use Cases

The following cases will be used to demonstrate accessing the TermHub Terminology API. These are the standard kinds of questions that a terminology server supports for interacting with code systems.

• Login
• Get terminologies
• Get project terminologies
• Get specific terminology
• Export terminology
• Get concept by code
• Get concept by code with explicit include parameter
• Get concept relationships by code
• Get concept inverse relationships by code
• Get concept trees
• Find concepts by search term (use paging to get only first 5 results)
• Find concepts by search term with explicit include parameter
• Find concepts by search term and expression
• Find terms by search term
• Support autocomplete/typeahead for first few characters typed
• Get mapsets
• Get project mapsets
• Get specific mapset
• Export mapset
• Get mappings for concept by code
• Find project mappings for mapset
• Find project mappings
• Get subsets
• Get project subsets
• Get specific subset
• Export subset
• Get subset members for project subset
• Coming Soon: compute "new" or "retired" codes across terminology versions

All of the tutorials use an environment variable for the API URL of the deployment:

• API_URL=https://api.terminologyhub.com

Back to top

Maintenance Commands

The project includes a root Makefile for the common upkeep workflow. Run these commands from the termhub-in-5-minutes directory.

Set credentials once in your shell before running checks that call authenticated TermHub endpoints. This means opening a terminal, running the two commands for your operating system, and then running the make command in that same terminal window. Replace <username> and <password> with your TermHub username and password, without the angle brackets. These settings only apply to the current terminal session, so set them again if you open a new terminal.

export TERMHUB_USER=<username>
export TERMHUB_PASSWORD=<password>

On Windows PowerShell:

$env:TERMHUB_USER="<username>"
$env:TERMHUB_PASSWORD="<password>"

For the bash examples on Windows, install Git for Windows or set BASH to a Windows-native bash.exe. The runner avoids WSL's C:\Windows\System32\bash.exe because WSL can fail when the Windows PATH contains drive paths it cannot translate.

$env:BASH="C:\Program Files\Git\bin\bash.exe"

Common targets:

make resample       # recreate curl, bash, Python, and Java sample files
make check          # run curl, bash, Python, Java, and FHIR checks
make fhir           # run both FHIR Postman collections with Newman
make scan           # run Trivy source and resolved dependency scans
make scan-strict    # same scan, but fail when vulnerabilities are found
make scan-prepare   # generate resolved dependency inputs under build/trivy
make regenerate     # regenerate Java and Python clients into doc/code-generator/build
make python-deps    # install generated Python client dependencies for the current user

The curl, bash, FHIR runner, and check orchestration scripts use only Python standard-library modules. The generated Python client still needs its generated dependencies; use make python-deps when running the Python client tests on a fresh machine. The Trivy dependency scan is prepared before it runs. For Python, it installs requirements into build/trivy/python-site and writes a pinned build/trivy/python/requirements.txt; for Java, it resolves Gradle dependencies and updates java-examples/gradle.lockfile.

Use API_URL, PROJECT, and PYTHON to override defaults, for example:

make check API_URL=https://api.terminologyhub.com PROJECT=sandbox PYTHON=python3

The curl and bash checks print the API_URL they are using. If you see a connection refused error, check whether your shell has an old API_URL pointing at a stopped local instance. You can also set TERMHUB_TOKEN or TOKEN to reuse an existing bearer token. Login examples avoid printing bearer tokens in automated output. Python saves its login token to python-examples/temp_token.txt for later Python tests, while the manual Bash and cURL login examples save a sourceable temp_token.env file in their example directories.

Back to top

Resources

• API Documentation - https://api.terminologyhub.com/terminology/doc/swagger-ui/index.html
• Additional Documentation

Back to top

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request

Back to top

Current Contributors

• Brian Carlsen
• Other Contributors

Back to top

License

See the included LICENSE.txt file for details.

Back to top