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:

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

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

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

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

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:

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

Remote Terminology Services