Smile CDR v2024.05.PRE
On this page:

9.10.1Package 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.

Package Registry Endpoint Architecture

9.10.2Swagger 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

9.10.3Operation: 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.

9.10.3.1Example

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
    }
  }
}

9.10.4Operation: 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.

9.10.4.1Example

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

9.10.5Operation: 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.

9.10.5.1Parameters

  • size: (optional) The number of results to return.
  • from: (optional) The offset/index of the first result to return.
  • _description: (optional) Search for packages that have this string within their description.
  • _url: (optional) Search for packages that provide a conformance resource with this canonical URL.
  • _fhirVersion: (optional) Search for packages that implement this FHIR version. Values can be a release name (e.g. 'R4' or a version string). Examples include R4 or 4.0.1.

9.10.5.2Example

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

9.10.6Operation: 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.

9.10.6.1Parameters

  • name: Specifies the NPM package name string, e.g. hl7.fhir.us.core.
  • version: Specifies the NPM package version stringm 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 reposutory or not. See Install Mode for more information and allowed values for this parameter.

9.10.6.2Example

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

9.10.7Operation: 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.

9.10.7.1Request Body

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

9.10.7.2Example

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

Request body:

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

9.10.8Operation: 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/uninstall/{package_id}/{version_id}. This operation is a Smile CDR extension on the NPM registry syntax.

9.10.8.1Example

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