9.9    Packages and Implementation Guides
  • Validation and Conformance
  • 9.0 Introduction
  • 9.1 Validation Support Repository
  • 9.2 Validation Support Repository Options
  • 9.3 Conformance Data
  • 9.4 Repository Validation
  • 9.5 Repository Validation: Java
  • 9.6 Repository Validation: Javascript
  • 9.7 Repository Validation: Validation Bean
  • 9.8 Endpoint Validation
  • 9.9 Packages and Implementation Guides
  • 9.10 Package Registry Endpoint Module
  • 9.11 Remote Terminology Services
  • 9.12 Suppressing Messages
  • 9.13 Validation Performance
  • 9.14 Automatic Provenance Injection
    • 9.11    Remote Terminology Services   
       Table of Contents

    Package Registry Endpoint Module

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

    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.5.3Response

    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
}

    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

       9.9    Packages and Implementation Guides
  • Validation and Conformance
  • 9.0 Introduction
  • 9.1 Validation Support Repository
  • 9.2 Validation Support Repository Options
  • 9.3 Conformance Data
  • 9.4 Repository Validation
  • 9.5 Repository Validation: Java
  • 9.6 Repository Validation: Javascript
  • 9.7 Repository Validation: Validation Bean
  • 9.8 Endpoint Validation
  • 9.9 Packages and Implementation Guides
  • 9.10 Package Registry Endpoint Module
  • 9.11 Remote Terminology Services
  • 9.12 Suppressing Messages
  • 9.13 Validation Performance
  • 9.14 Automatic Provenance Injection
    • 9.11    Remote Terminology Services