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": [
      "https://roche.com/fhir/iop/StructureDefinition/rdc-Subscription"
    ]
  },
  "topic": "https://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 client subscribes to receive notifications about created or updated BG measurement resources via REST hook (as specified by the channelType field).

The request asks for notification to be POST-ed to the to the URL specified in the endpoint field. The content field determines how much information about the created/updated resources should be included in the notification. Its value can be set to either id-only or empty. In the case of id-only, the server will send notifications with a payload containing ID-s of the relevant resources. The ID-s of the resources are not present in the case of empty content. See page Handling notifications for examples of the notification content and for the description of 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: