RDC Interoperability Guide

Creating and updating subscriptions

A client can create a subscription by POST-ing a Subscription resource to the server's Subscription endpoint. For example:

curl -sS -X POST --json @subscription.json "https://${server}/fhir/r5/api/Subscription" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Where subscription.json is a file with following contents:

{
  "resourceType": "Subscription",
  "meta": {
    "profile": [
      "http://roche.com/fhir/iop/StructureDefinition/Subscription"
    ]
  },
  "topic": "http://roche.com/fhir/iop/SubscriptionTopic/BgMeasurements",
  "status": "requested",
  "filterBy": [
    {
      "filterParameter": "organization",
      "value": "3156089"
    }
  ],
  "channelType": {
    "code": "rest-hook"
  },
  "endpoint": "https://${server-of-subscriber}/subscription-notification",
  "contentType": "application/fhir+json",
  "content": "id-only"
}

This request sets up a subscription for BG measurements (as specified by the topic field) for the entire organization (as specified by the filterBy field), which means data for all patients of the organization. (Please note that for the time being, the organization specified in the filter must match the organization creating the subscription.)

The request asks for notification to be POST-ed to the to the URL specified in the endpoint field with a payload containing ID-s of matching resources (as specified by the content field). The next section deals with the proper handling of these notifications.

An existing subscription can be updated by sending the desired subscription state in an HTTP PUT request to URL corresponding to the specific subscription, for example:

curl -sS -X PUT --json @updated-subscription.json "https://${server}/fhir/r5/api/Subscription/42" \
  -H "client_id: ${client_id}" \
  -H "client_secret: ${client_secret}" \
  -H "org_id: ${org_id}" \
  -H "certificate: ${certificate}" | jq

Handshake notifications

Each subscription has a notification endpoint URL associated with it that should reside in the subscriber's infrastructure. When a subscriber requests a subscription to be created or certain fields of an existing subscription to be updated, the server POST-s a handshake notification to the notification endpoint URL with a payload similar to the following:

{
    "resourceType": "Bundle",
    "type": "subscription-notification",
    "entry": [
        {
            "resource": {
                "resourceType": "SubscriptionStatus",
                "status": "requested",
                "type": "handshake",
                "eventsSinceSubscriptionStart": 0,
                "subscription": {
                    "reference": "Subscription/42"
                }
            }
        }
    ]
}

The notification endpoint needs to acknowledge the receipt of the handshake by returning an HTTP 200 OK status. The server will not create or update the subscription until this. (The server sends the handshake while serving the subscriber's request and will only respond once the handshake succeeded or failed - either explicitly or with a timeout).

Sequence diagram

The full subscription creation and update workflow including handshake notifications can be represented in a sequence diagram as follows: