This module is not required in order to use packages. If you simply want to load packages and use them for validation, you can use Package Spec file to upload your packages, as decribed in Pre-Seeding Packages and FHIR Resources. However, the package registry provides a dedicated HTTP endpoint that can be used to access and submit packages to storage in the FHIR Storage (RDBMS) module.

You can directly interact with the package registry using any NPM client, using direct HTTP requests, or through the built-in Swagger-UI support. You can also use the endpoint to serve as an enterprise package registry which seeds packages to other servers in your organization.

Swagger UI

The NPM syntax uses the terms "Package ID" and "Package Name" interchangeably. These two terms refer to the same concept on this page.

Accessing and testing the Package Registry endpoint can be done using a browser with Swagger UI.

To access this use the following URL, substituting your configured host and port. The example below uses the port in the default Smile CDR configuration: http://localhost:8002/swagger-ui.html

Operation: Fetch Metadata By Package ID

The Fetch Metadata By Package ID operation searches for any package versions and metadata associated with the given NPM Package ID string.

This operation uses an HTTP GET to the path /npm/{package_id}. This operation is a standard NPM operation and should be accessible from any NPM compatible client.

Example

The following URL shows an example of this operation. GET http://localhost:8002/npm/hl7.fhir.us.core

An example response is shown below:

{
  "dist-tags": {
    "latest": "5.0.1"
  },
  "versions": {
    "5.0.1": {
      "name": "hl7.fhir.us.core",
      "version": "5.0.1",
      "description": "The US Core Implementation Guide is based on FHIR Version R4 and defines the minimum conformance requirements for accessing patient data. The Argonaut pilot implementations, ONC 2015 Edition Commo...",
      "fhirVersion": "4.0.1",
      "_bytes": 1310494
    }
  }
}

Operation: Fetch Package

The Fetch Package operation fetches the complete NPM package (i.e. the .tgz file containing the package itself) from the server to the client.

This operation uses an HTTP GET to the path /npm/{package_id}/{version_id}. This operation is a standard NPM operation and should be accessible from any NPM compatible client.

Example

The following URL shows an example of this operation. GET http://localhost:8002/npm/hl7.fhir.us.core/5.0.1

Operation: Search For Packages

The Search For Packages operation searches for installed packages matching various query parameters.

This operation uses an HTTP GET to the path /npm/-/v1/search. This operation is a standard NPM operation and should be accessible from any NPM compatible client.

Parameters

size: (optional) The number of results to return.
from: (optional) The offset/index of the first result to return.
_description: (optional) Search for package versions that have this string within their description. This parameter is case-insensitive.
_author: (optional) Search for packages that have this string within their author. This parameter is case-insensitive.
_url: (optional) Search for packages that provide a conformance resource with this canonical URL.
_version: (optional) Search for packages have a specific package version (not FHIR version).
_fhirVersion: (optional) Search for packages that implement this FHIR version (not package version). Values can be a release name (e.g. 'R4' or a version string). Examples include R4 or 4.0.1.

Example

The following URL shows an example of this operation. GET http://localhost:8002/npm/-/v1/search?size=200&from=0&_fhirVersion=ONC

Response

The following snippet shows a sample response:

{
  "objects" : [ {
    "package" : {
      "name" : "com.smilecdr",
      "version" : "1.0.0",
      "author" : "Smile Digital Health",
      "description" : "This is an example package for Smile Digital Health",
      "_bytes" : 1000
    }
  } ],
  "total" : 0
}

Operation: Find Package Asset Info

The Load Package Info operation searches for installed packages and resources matching a search by FHIR version and canonical URL.

This operation uses an HTTP GET to the path /npm/-/v1/loadResourcePackageInfosByUrl.

This operation is a Smile CDR extension on the NPM registry syntax.

Parameters

_fhirVersion: Search for packages that implement this FHIR version (not package version). Values can be a release name (e.g. 'R4' or a version string). Examples include R4 or 4.0.1.
_canonicalUrl: Search for packages and resources with this canonical URL. Example: http://example.com/Measure/simple-alpha.

Example

The following URL shows an example of this operation. GET http://localhost:8002/npm/-/v1/loadResourcePackageInfosByUrl?_fhirVersion=R4&_canonicalUrl=http%3A%2F%2Fexample.com%2FMeasure%2Fsimple-alpha

Response

The following snippet shows a sample response:

{
  "npmFhirIdPackageIdAndVersionJsons": [
    {
      "Resource ID": "Binary/1327",
      "Canonical URL": "http://example.com/Measure/simple-alpha",
      "FHIR Version": "R4",
      "Package ID": "simple-alpha-dupe",
      "Package Version": "0.5"
    },
    {
      "Resource ID": "Binary/1330",
      "Canonical URL": "http://example.com/Measure/simple-alpha",
      "FHIR Version": "R4",
      "Package ID": "simple-alpha",
      "Package Version": "0.1"
    }
  ]
}

Operation: Find Package Resource JSON

The Load resource JSON by FHIR version, Canonical URL, package ID and package version operation searches for resource JSON matching a search by FHIR version and canonical URL, package ID and package version.

This operation uses an HTTP GET to the path /npm/-/v1/loadResourceJson.

This operation is a Smile CDR extension on the NPM registry syntax.

Parameters

_fhirVersion: Search for packages that implement this FHIR version (not package version). Values can be a release name (e.g. 'R4' or a version string). Examples include R4 or 4.0.1.
_canonicalUrl: Search for resources with this canonical URL. Example: http://example.com/Measure/simple-alpha.
_packageId: Search for resources with this package ID. Example: simple-alpha.
_versionID: (optional) Search for resources with this package version. Example: 0.2.

Example

The following URL shows an example of this operation. GET http://localhost:8002/npm/-/v1/loadResourceJson?_fhirVersion=R4&_canonicalUrl=http%3A%2F%2Fexample.com%2FMeasure%2Fsimple-alpha&_packageId=simple-alpha-dupe&_packageVersion=0.5

Response

The following snippet shows a sample response:

{
  "resourceType": "Measure",
  "id": "simple-alpha",
  "url": "http://example.com/Measure/simple-alpha",
  "version": "0.2",
  "name": "simple-alpha",
  "library": [
    "http://example.com/Library/simple-alpha"
  ]
}

Operation: Install By Param

The Install by Param operation uses an NPM package name and version string to trigger uploading a package.

This operation uses an HTTP PUT to the path /write/install/by-param. This operation is a Smile CDR extension on the NPM registry syntax.

Parameters

name: Specifies the NPM package name string, e.g. hl7.fhir.us.core.
version: Specifies the NPM package version string, e.g. 5.0.1.
fetchDependencies: Specifies whether NPM module dependencies should also be installed. See Fetch Dependencies for more information and allowed values for this parameter.
installMode: Specifies whether the package resources should be installed discretely in the repository or not. See Install Mode for more information and allowed values for this parameter.
versionPolicy: Controls how resource versions are handled during installation. Only applies when installMode is STORE_AND_INSTALL. See Version Policy for more information. Allowed values are MULTI_VERSION (default) and SINGLE_VERSION.

Example

The following URL shows an example of this operation. PUT http://localhost:8002/write/install/by-param?name=hl7.fhir.us.core&version=5.0.1&fetchDependencies=false&installMode=STORE_ONLY

Operation: Install By Spec

The Install by Spec operation uses a Package Spec file as input to trigger uploading a package.

This operation uses an HTTP PUT to the path /write/install/by-spec. This operation is a Smile CDR extension on the NPM registry syntax.

Request Body

The request payload is a JSON document containing a Package Spec. See the PackageInstallationSpec model for information on this format.

The following properties are supported:

Property	Type	Default	Description
name	String		The NPM package name.
version	String		The package version.
packageUrl	String		Specifies where to download the package from. Supports `http://` and `https://` (remote download), `classpath:` (bundled in the server classpath, e.g. `classpath:/my-package.tgz`), and `file:` (local filesystem, e.g. `file:///data/packages/my-package.tgz`). The URL must be covered by the Allowed Package URLs (whitelist).
installMode	Enum		Controls how the package is handled. `STORE_ONLY` downloads and caches the package locally but does not install resources into the repository. `STORE_AND_INSTALL` downloads, caches, and installs resources into the repository. `INSTALL_ONLY` installs resources into the repository but does not cache the package locally. See Install Mode for more information.
installResourceTypes	String[]	All conformance types	The resource types to extract and install from the package. By default all conformance resources are installed (e.g. `CodeSystem`, `ValueSet`, `StructureDefinition`, `SearchParameter`, `ConceptMap`, `NamingSystem`, `Subscription`).
reloadExisting	boolean	true	Whether to update resources that already exist in the repository. When false, existing resources are skipped.
fetchDependencies	boolean	false	Whether to automatically resolve, fetch, and install package dependencies. See Fetch Dependencies for more information.
dependencyExcludes	String[]		A list of Java regular expressions. When `fetchDependencies` is enabled, any transitive dependency whose package ID matches a pattern in this list will be skipped. See Dependency Excludes for details and examples.
versionPolicy	Enum	MULTI_VERSION	Controls resource ID assignment for new resources and how canonical resources are matched. `MULTI_VERSION` assigns server-generated IDs to new resources (except `SearchParameter`) and matches existing canonical resources by URL and version, allowing multiple versions to coexist. `SINGLE_VERSION` retains client-assigned IDs from the package and matches existing canonical resources by URL only (ignoring version), so a new version overwrites the existing one. See Resource Matching for how non-canonical resource types are matched, and Version Policy for full details.
overwriteContentNotPresentCodeSystems	boolean	false	When true, a `CodeSystem` with `content=not-present` will be overwritten by a `CodeSystem` from the package. By default, these `CodeSystem` resources are protected since their concepts are stored in terminology tables (e.g. via `$upload-external-code-system`) and would be lost if overwritten.
additionalResourceFolders	String[]		A list of additional folders within the package to scan for resources. By default, only the main `package` folder is scanned. Some packages (such as published IGs) include an `example` folder containing sample resources. Adding `"example"` to this list will install those resources alongside the main package contents.
dryRun	boolean	false	When true, no changes are persisted and a report is generated outlining what changes would result from the installation.

Example

The following URL shows an example of this operation. PUT http://localhost:8002/write/install/by-spec

Request body:

{
  "name" : "hl7.fhir.us.core",
  "version" : "5.0.1",
  "packageUrl" : "classpath:/hl7.fhir.us.core-5.0.1.tgz",
  "installMode" : "STORE_ONLY",
  "installResourceTypes" : [ "*" ],
  "reloadExisting" : true,
  "fetchDependencies" : true
}

Batch Processing

By default, the install operation runs synchronously, meaning the HTTP call blocks until installation completes. For large IGs with many dependencies, this can take several minutes or more and may time out depending on your HTTP client or load balancer configuration.

Calling the operation with the HTTP header Prefer: respond-async will start a batch job to install the package as an asynchronous background process. In this mode, the call will return HTTP response code 202 Accepted, and the response header content-location will provide a URL that can be queried to check the status of a running job. Job status can also be monitored through the Batch Job Management page of the administration console.

Asynchronous installation is recommended when:

Installing IGs with many transitive dependencies
Running in environments with short HTTP timeouts
You want to monitor progress in the admin console rather than waiting for the HTTP response

Operation: Delete By Spec

The Delete by Spec operation uses a Package Spec file as input to trigger deletion of a package.

This operation uses an HTTP DELETE to the path /write/{package_id}/{version_id}. This operation is a Smile CDR extension on the NPM registry syntax.

Example

The following URL shows an example of this operation. DELETE http://localhost:8002/write/hl7.fhir.us.core/5.0.1

Packages and Implementation Guides Remote Terminology Services