Subscribing to Topics

Client Systems may subscribe to Topics to receive notifications when events on that topic occur in future. When subscribing, Client Systems must specify a filter which will be applied to events to ensure that only notifications which are relevant to the client are sent. Clients may choose between two Subscription Types - rest-hook or event-pull - to determine whether they wish to receive push notifications or to use a polling mechanism. Client Systems wishing to use rest-hook must first set up an endpoint within their infrastructure, and register it with the Spine. Please see Working with Endpoints for further details.

Subscribe to a Topic using a Rest Hook

POST /Subscription

When creating or updating an Subscription of type rest-hook, the Spine will send a handshake notification to the endpoint using the POST method. The endpoint must return a success status otherwise the Subscription will not be created and an error response will be returned.

Parameters

Name

Type

Description

body

JSON Object (body)

Example

JSON

{
    "resourceType": "Subscription",
    "status": "active",
    "topic": "https://clevermed.com/fhir/r5/SubscriptionTopic/pregnancy-event",
    "end": "2023-01-07T11:15:18Z",
    "filterBy": [
        {
            "filterParameter": "patient-id",
            "value": "c9ccbed5-7bce-4b49-8b90-00600733a891"
        }
    ],
    "channelType": {
        "system": "http://hl7.org/fhir/subscription-channel-type",
        "code": "rest-hook"
    },
    "extension": [
        {
            "url": "https://clevermed.com/fhir/StructureDefinition/BNetEndpoint",
            "valueReference": {"reference" : "Endpoint/e7ed0ca6-f9ec-42f8-9e60-b7bd6fce1096"}
        }
    ],
    "heartbeatPeriod": 3600,
    "maxCount": 50,
    "content": "id-only"
}

channelType:
- System: http://hl7.org/fhir/subscription-channel-type
- Code: rest-hook
status: Only active is currently supported
content: Must be set to id-only
Endpoint Extension: Must reference an existing endpoint
heartbeatPeriod: Optionally sends a heartbeat notification to the endpoint at this interval in seconds.
- null or 0: No Heartbeat will be sent
- Minimum: 60 (1 minute)
- Maximum: 86400 (24 hours)
maxCount: The maximum number of events to include in each notification sent to the endpoint
- Required for Rest Hook subscriptions
- Minimum: 1
- Maximum: 50

Responses

Code

Description

201

Created

See response header: X-Logical-Id to obtain the ID of the created record

422

Unprocessable Entity

Subscribe to a Topic using Event Pull

POST /Subscription

When creating or updating an Subscription of type event-pull, the Spine will not send notifications to an endpoint when events occur. Instead, it is the responsibility of the Client System to poll the Events endpoint to retrieve events.

Parameters

Name

Type

Description

body

JSON Object (body)

Example

JSON

{
    "resourceType": "Subscription",
    "status": "active",
    "topic": "https://clevermed.com/fhir/r5/SubscriptionTopic/pregnancy-event",
    "end": "2023-01-07T11:15:18Z",
    "filterBy": [
        {
            "filterParameter": "patient-id",
            "value": "c9ccbed5-7bce-4b49-8b90-00600733a891"
        }
    ],
    "channelType": {
        "system": "https://clevermed.com/fhir/r5/CodeSystem/subscription-channel-type",
        "code": "event-pull"
    },
    "content": "id-only"
}

channelType:
- System: https://clevermed.com/fhir/r5/CodeSystem/subscription-channel-type
- Code: event-pull
status: Only active is currently supported
content: Must be set to id-only

Responses

Code

Description

201

Created

See response header: X-Logical-Id to obtain the ID of the created record

422

Unprocessable Entity

Get Subscription

GET /Subscription/{subscription-id}

Parameters

Name	Type	Description
`subscription-id`	String (path)	The ID of the Subscription to get

Responses

Code

Description

200

Example

JSON

{
    "resourceType": "Subscription",
    "id": "08d15860-abab-499e-bc47-9517488383c2",
    "extension": [
        {
            "url": "https://clevermed.com/fhir/StructureDefinition/BNetEndpoint",
            "valueReference": {
                "reference": "Endpoint/e0da4cd5-8ec9-4a69-afcb-1bed685f8677"
            }
        }
    ],
    "status": "active",
    "topic": "https://clevermed.com/fhir/r5/SubscriptionTopic/pregnancy-event",
    "end": "2023-01-07T11:15:18+00:00",
    "filterBy": [
        {
            "filterParameter": "patient-id",
            "value": "c9ccbed5-7bce-4b49-8b90-00600733a891"
        }
    ],
    "channelType": {
        "system": "http://hl7.org/fhir/subscription-channel-type",
        "code": "rest-hook"
    },
    "heartbeatPeriod": 3600,
    "maxCount": 50,
    "content": "id-only"
}

404

Not Found

Get all Subscriptions

GET /Subscription

Responses

Code

Description

200

Example

JSON

{
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 2,
    "entry": [
        {
            "resource": {
                "resourceType": "Subscription",
                // etc
            },
            "search": {
                "mode": "match"
            }
        },
        {
            "resource": {
                "resourceType": "Subscription",
                // etc
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

Update Subscription

PUT /Subscription/{subscription-id}

Parameters

Name	Type	Description
`subscription-id`	String (path)	The ID of the Subscription to Update
`body`	JSON Object (body)	JSON model as for Create

Responses

Code	Description
204	Success - No Content
404	Not Found

Delete Subscription

DELETE /subscription/{subscription-id}

Parameters

Name	Type	Description
`Subscription-id`	String (path)	The ID of the Subscription to Delete

Responses

Code	Description
204	Success - No Content
404	Not Found

Get Subscription Status

GET /Subscription/{subscription-id}/$status

Parameters

Name	Type	Description
`subscription-id`	String (path)	The ID of the Subscription to get the status for

Responses

Code

Description

200

Example

JSON

{
    "resourceType": "Bundle",
    "id": "43d363da-5aa6-4325-93a5-23bc60b987ec",
    "type": "collection",
    "timestamp": "2022-11-30T22:06:30.2650532+00:00",
    "entry": [
        {
            "resource": {
                "resourceType": "SubscriptionStatus",
                "id": "4d6fb120-2ab2-47d1-8c4c-7f5a30fd9738",
                "status": "active",
                "type": "query-status",
                "eventsSinceSubscriptionStart": 754,
                "subscription": {
                    "reference": "Subscription/e22e94df-f2f9-4cc4-ae56-62950e95f2d6"
                },
                "topic": "https://clevermed.com/fhir/r5/SubscriptionTopic/pregnancy-event"
            }
        }
    ]
}

404

Not Found