Package Registry Endpoint Module - Smile CDR Documentation
Package Registry Endpoint module
A module called the Package Registry Endpoint module provides an NPM compatible REST API that can be used to:
Load new packages into package storage
Query for and access packages stored in package storage
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
}
}
}
Copy
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
R4or4.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
}
Copy
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
R4or4.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"\
}\
]
}
Copy
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
R4or4.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"\
]
}
Copy
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
installModeisSTORE_AND_INSTALL. See Version Policy for more information. Allowed values areMULTI_VERSION(default) andSINGLE_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
}
Copy
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
Package Registry Endpoint Module
Validation and Conformance
Introduction Validation Support Repository Validation Support Repository Options Conformance Data Repository Validation Repository Validation: Java Repository Validation: Javascript Repository Validation: Custom Validation Beans Endpoint Validation Packages and Implementation Guides Package Registry Endpoint Module Remote Terminology Services Suppressing Messages Validation Performance Automatic Provenance Injection