As explained in its Exchange Module, the FHIR standard RESTful API is a general-purpose interface that can be used to push and pull data between systems. Which is appropriate depends on architecture and deployment considerations.

This page guides the various possibilities of interactions between a catalog custodian and a catalog consumer, as well as between a catalog owner and a catalog custodian when these two roles happen to be played by two distinct systems. These three roles are defined in section Scope and Roles of the Home page of this guide. This guidance is applicable to any kind of catalog (drugs, devices, knowledge artifacts, laboratory services ...)

Search and retrieve content from a catalog (pull mode)

Implementations of FHIR Catalog commonly assign a FHIR server to the system playing the role of catalog custodian, and FHIR clients to the systems playing the role of catalog consumer. This architectural choice is the one that minimizes the implementation cost on the consumer side, which is by far, the side with the biggest number of stakeholders. In this architecture, consumers search through the catalog and pull the content they are interested in using http GET commands, conforming to the FHIR RESTful API.

This most common mode of interaction is further guided for each kind of catalog, in the pages of this guide, accessible through the Specification option of the top menu bar.

Import a catalog or a subset of it (pull mode)

A catalog consumer may want to import the content of a full catalog or of a subset of it onto its own system. To do so, the catalog consumer uses an http GET interaction, positioning appropriate search parameters to delineate the content it wants to import.

Among these parameters, the catalog consumer SHALL use the _include:iterate=* parameter, in order to instruct the catalog custodian to return not only the resources representing the overview of the catalog items, but also all the supporting resources referenced by these, so as to obtain the fully detailed definition of each item in the imported catalog.

Given the fact that catalogs are often cumbersome objects, the catalog custodian is expected to use the paging mechanism to split its response into as many pages as needed, as specified in the FHIR RESTful API.

The catalog consumer may indicate its own maximum limit by providing the _count parameter with the maximum number of resources to be returned in a single Bundle page, as explained in FHIR Search specification.

Except in case of error, the response from the server is a Bundle resource, with:

• Bundle.type = searchset
• Bundle.total = [total number of resources contained in the imported catalog (or catalog subset)]

As said above, the Bundle may be split in pages, in which case each page contains these elements:

• Bundle.link with relation = self and url = [the current Bundle page]
• Bundle.link with relation = first and url = [the first Bundle page]
• Bundle.link with relation = previous and url = [the previous Bundle page] (except on the first page)
• Bundle.link with relation = next and url = [the next Bundle page] (except on the last page)
• Bundle.link with relation = last and url = [the last Bundle page]

The links are opaque to the client, have no dictated structure, and only the catalog server understands them. The catalog consumer requests the next page using an http GET [url associated with the current Bundle.link.relation = next] until the last page is reached.

The catalog consumer can, thus, maintain its own local copy of a subset of the catalog. This local copy has of course its own physical url for each of its resources. The canonical url of each resource is used to manage the updates: When importing a new update from the global catalog, the canonical url of each resource is used to match the new instance imported to the previous version stored locally.

Push mode interactions: export and update

A catalog custodian may have agreed to work in push mode with some of its consumers, for instance to support use case Customized catalog shared in push mode depicted in the Laboratory services use cases section of this guide. To implement such a use case, the messaging paradigm is chosen as it is the least intrusive on the catalog consumer side. Thus, in case they want to support push interactions, catalog custodians and consumers rely on the FHIR messaging framework. In particular, the consumer must be able to receive request messages from the catalog custodian and to send back response messages to it. The request message consists of a Bundle of type "message", with the first resource in the bundle being a MessageHeader. The event representing the kind of request is populated in MessageHeader.eventCoding. Two events are defined:

• full-catalog requests the receiver to initialize (or reinitialize) its local catalog from the content of the received message, which represents the comprehensive content of the local catalog.
• update-catalog requests the receiver to update its local catalog from the content of the received message, which represents the differential, i.e. the resources that need to be inserted or updated into the local catalog.

The other resources in the Bundle represent the content of the catalog (or of its update). The first of these resources is the Composition resource representing the catalog header.

One way to proceed is to initialize the consumer's local catalog with the catalog custodian sending a message with the full-catalog event, and from that point, sending only updates (with the update-catalog event) on a regular basis.

The exact mechanism of transfer of the messages from source to destination is irrelevant to the FHIR standard as well as to this implementation guide. It may include file transfer, HTTP based transfer, MLLP (HL7 minimal lower layer protocol), MQ series messaging or anything else. The only requirement for the transfer layer is that requests are sent to a known location and responses are returned to the source of the request.

For this messaging paradigm, this implementation guide provides the CatalogMessageDefinition profile of the MessageDefinition resource, with two examples:

• example-message-definition-initialize,
• example-message-definition-update.

Administer a catalog through the FHIR API between catalog owner and catalog custodian

The catalog owner may manage the content of its catalog in its own proprietary format, delegating to a third party the role of catalog custodian (i.e. the organization and system publishing the catalog as a set of sharable FHIR resources towards the catalog consumers. In this configuration, the catalog owner is a FHIR client with additional permissions (create, update, delete, patch) on catalog resources of the catalog custodian. The other clients representing catalog consumers only have the read permission.

Stewardship of the catalog content is handled through FHIR (create|read|update|patch|delete) interactions initiated by the catalog owner towards the catalog custodian.

In most kinds of catalogs an item usually needs more than one resource for its full representation. For instance in a laboratory compendium, a laboratory service is represented by a PlanDefinition associated with a number of {ActivityDefinition} + {SpecimenDefinition} + {ObservationDefinition}. Thus inserting a new item in a catalog, or updating it, or removing it needs a simultaneous and consistent set of interactions on multiple resources in the catalog. For this reason, the catalog owner administers the content of the catalog in a transactional manner, interacting with the catalog custodian by posting a transaction Bundle to it, and checking the transaction-response Bundle from it to ensure good synchronization of the catalog content across both parties.

This implementation guide provides for this purpose these two profiles of the Bundle resource:

• The ItemTransactionRequest profile constraining transaction Bundle posted by the catalog owner; see also the example-lab-test-creation-transaction-request.
• The ItemTransactionResponse profile constraining transaction-response Bundle returned back by the catalog custodian; See also the example-lab-test-creation-transaction-response.

Delete operations requested atomically by the catalog owner are to be accepted and performed by the catalog custodian after having checked that the resource to be deleted is not referenced by any other resource. If this is not the case the operation is rejected with an OperationOutcome. In the case of a transaction request containing a delete operation, this operation will be performed only if the resource to be deleted is not referenced from elsewhere given all other operations of the transaction. If it is not the case the whole transaction is rejected with an OperationOutcome.

Combining pull mode with subscriptions to notifications in push mode

The subscription mechanism is used to establish proactive event notifications from a FHIR server to another system. Implementing this mechanism in the context of this guide allows catalog consumers to request event notifications from a catalog custodian. These event notifications are subscribed by the catalog consumers, within a predefined topic supported by the catalog custodian. The consumers can further refine the notifications they expect, by selecting filters, among those predefined for the topic by the catalog custodian.

This subscription mechanism is more properly defined in R5 and is to be specified in detail here as the IG is migrated to R5. The mechanism uses the two resources Subscription (posted by the catalog consumer) and Topic (published by the catalog custodian). An instance of Subscription represents a request for notifications of events, which are described in the Topic resource referenced by this instance.

To be continued now that the IG is migrated to R5