Aidbox
Ask or search…
K

Subscription API

Create Subscription - POST /fhir/Subscription

Creates a new subscription. Takes params depending on the current version of FHIR used in Aidbox.
The R4B Subscriptions resource uses FHIR extension fields that should be written according to the specification. You should also add the subscription backport profile URL to your resource's meta.profile field.

Params:

R4B
R5
Parameter
Type
Required
Description
meta
object
meta.profile
string[]
id
string
Identifier of the resource. Will be auto-generated if not provided.
reason
string
Human readable reason for subscription.
criteria
string
Canonical URL for the topic used to generate events.
Example: http://aidbox.app/SubscriptionTopic/patient-test-1
criteria.extension:
string[]
The filters applied to events in the following format:
[resourceType.]filterParameter=[modifier]value
filterParameter above should be one of the filter names defined by the relevant SubscriptionTopic
(canFilterBy.filterParameter field).
resourceType and modifiers should be the ones allowed in the corresponding canFilterBy.filterParameter of the relevant SubscriptionTopic as well.
resourceType is only necessary for disambiguation.
When multiple filters are applied, it evaluates to true if all the conditions applicable to that resource are met; otherwise, it returns false (i.e., logical AND).
Example: patient-birth=gt2005-01-01T01:00:00Z
channel.extension:
integer
Interval in seconds to send 'heartbeat' notification.
Default value: 120
channel.extension:
timeout
integer
Timeout in seconds to attempt notification delivery.
Default value: 30
channel.extension:
maxCount
integer
Maximum number of triggering resources included in notification bundles.
Default value: 10
channel.type
string
The type of channel to send notifications on. Supported values: rest-hook
channel.header
string[]
Additional headers/information to send as part of the notification. For the rest-hook channel type, this will be HTTP request headers.
Example: ["random-header: secret123"]
channel.endpoint
string
The URL that describes the actual end-point to send messages to.
Example: https://my.app/endpoint
channel.payload
string
MIME-type to send, or omit for no payload. Supported values: application/fhir+json
channel.payload.extension:
content
string
Supported values: empty, id-only, full-resource.
Default value: empty
status
string
Status of the subscription.
On the creation of this resource, the status is always requested and other values will be ignored.
end
string
When to automatically delete the subscription.
Parameter
Type
Required
Description
id
string
Identifier of the resource.
Default value: generated
topic
string
Url reference to subscription topic.
Example: http://aidbox.app/SubscriptionTopic/patient-test-1
status
string
Status of the subscription.
On the creation of this resource, the status is always requested and other values will be ignored.
reason
string
Human readable reason for Subscription.
filterBy
object[]
Filters applied to the resources that would be included in the notification. When multiple filters are applied to one resource type, evaluates to true if all the conditions are met.
filterBy.resourceType
string
Resource for this Subscription filter. Example: Patient
filterBy.filterParameter
string
Filter label defined in SubscriptionTopic.
filterBy.value
string
Literal value or resource path.
filterBy.comparator
string
Comparator applied to this filter parameter. Should be allowed in SubscriptionTopic resource. Supported values: eq, gt, lt, ge, le.
filterBy.modifier
string
Modifier applied to this filter parameter. Should be allowed in SubscriptionTopic resource. Supported values: temporary not supported.
channelType
object
The type of channel to send notifications on.
channelType.system
string
channelType.code
string
The type of channel to send notifications on. Supported values: rest-hook
endpoint
string
The url that describes the actual end-point to send notifications to.
heartbeatPeriod
integer
Interval in seconds to send 'heartbeat' notification.
parameter
object[]
Additional headers/information to send as part of the notification. For the rest-hook channel type, this will be HTTP request headers.
parameter.name
string
Example: "random-header".
parameter.value
string
Example: "secret123".
timeout
integer
Timeout in seconds to attempt notification delivery.
content
string
How much of the resource content to deliver in the notification payload. The choices are an empty payload, only the resource id, or the full resource content. Supported values: empty, id-only, full-resource
maxCount
integer
Maximum number of events that can be combined in a single notification.
end
string
When to automatically delete the subscription.

Result:

Parameter
Type
Description
resource
object
Created Subscription resource.
Request
Response
POST /fhir/Subscription
content-type: text/yaml
accept: text/yaml
meta:
profile:
- http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
criteria: http://aidbox.app/SubscriptionTopic/patient-test-1
channel:
extension:
- url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period
valueUnsignedInt: 60
- url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout
valueUnsignedInt: 1
- url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count
valuePositiveInt: 2
type: rest-hook
endpoint: http://localhost:27193/patient-test-1
payload: application/fhir+json
_payload:
extension:
- url: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content
valueCode: id-only
resourceType: Subscription
reason: R4/B Test Topic-Based Subscription for Patient resources
status: active
id: subscription-patient-test-1
end: '2020-12-31T12:00:00Z'
Status: 201
meta:
profile:
- >-
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
lastUpdated: '2023-09-06T07:03:26.763869Z'
versionId: '735'
extension:
- url: http://example.com/createdat
valueInstant: '2023-09-06T07:03:26.763869Z'
criteria: http://aidbox.app/SubscriptionTopic/patient-test-1
channel:
type: rest-hook
payload: application/fhir+json
extension:
- url: >-
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout
valueUnsignedInt: 1
- url: >-
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count
valuePositiveInt: 2
- url: >-
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period
valueUnsignedInt: 60
_payload:
extension:
- url: >-
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content
valueCode: id-only
endpoint: http://localhost:27193/patient-test-1
resourceType: Subscription
reason: R4/B Test Topic-Based Subscription for Patient resources
status: requested
id: subscription-patient-test-1
end: '2020-12-31T12:00:00Z'

Subscription Status - GET /fhir/Subscription/[id]/$status

This operation is used to get the current status information about a topic-based Subscription.
Returns FHIR bundle where the SubscriptionStatus resource is the only entry element.

Params:

No params are required.
Request
Response
GET /fhir/Subscription/subscription-patient-test-1/$status
content-type: text/yaml
accept: text/yaml
Status: 200
resourceType: Bundle
type: history
timestamp: '2023-09-06T07:25:19.631905713Z'
entry:
- resource:
resourceType: SubscriptionStatus
status: active
type: query-status
eventsSinceSubscriptionStart: 0
subscription:
reference: http://aidbox.app/fhir/Subscription/subscription-patient-test-1
topic: http://aidbox.app/SubscriptionTopic/patient-test-1

Subscription Events - GET /fhir/Subscription/[id]/$events

This operation is used to search for and get notifications that have been previously triggered by a topic-based Subscription.
Returns FHIR bundle where the SubscriptionStatus resource is the first entry element, and triggered events are the rest.

Params:

Parameter
Type
required
Description
eventsSinceNumber
integer
The starting event number, inclusive of this event (lower bound).
eventsUntilNumber
integer
The ending event number, inclusive of this event (upper bound).
If the params above are not provided, returns the latest 20 events.
Request
Response
GET /fhir/Subscription/subscription-patient-test-1/$events
content-type: text/yaml
accept: text/yaml
Status: 200
resourceType: Bundle
type: history
timestamp: '2023-09-06T07:40:59.527416959Z'
entry:
- resource:
resourceType: SubscriptionStatus
status: active
type: query-event
eventsSinceSubscriptionStart: 19
subscription:
reference: http://aidbox.app/fhir/Subscription/subscription-patient-test-1
topic: http://aidbox.app/SubscriptionTopic/patient-test-1
notificationEvent:
- eventNumber: 1
timestamp: '2023-09-04 10:38:43.020984+03'
focus:
reference: >-
http://aidbox.app/fhir/Patient/c868fc6f-0631-43cc-940a-c43177fe6567
- eventNumber: 2
timestamp: '2023-09-04 10:38:44.382835+03'
focus:
reference: >-
http://aidbox.app/fhir/Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
- eventNumber: 3
timestamp: '2023-09-04 10:38:44.888717+03'
focus:
reference: >-
http://aidbox.app/fhir/Patient/98485698-083d-4659-8869-b4f0d87734ac
- eventNumber: 4
timestamp: '2023-09-04 10:38:45.031019+03'
focus:
reference: >-
http://aidbox.app/fhir/Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
- eventNumber: 5
timestamp: '2023-09-04 10:38:45.171641+03'
focus:
reference: >-
http://aidbox.app/fhir/Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
- fullUrl: http://aidbox.app/fhir/Patient/c868fc6f-0631-43cc-940a-c43177fe6567
request:
method: POST
url: Patient/c868fc6f-0631-43cc-940a-c43177fe6567
response:
status: '201'
- fullUrl: http://aidbox.app/fhir/Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
request:
method: POST
url: Patient/fe174a4e-e3ba-4d75-98b6-17fea275dda1
response:
status: '201'
- fullUrl: http://aidbox.app/fhir/Patient/98485698-083d-4659-8869-b4f0d87734ac
request:
method: POST
url: Patient/98485698-083d-4659-8869-b4f0d87734ac
response:
status: '201'
- fullUrl: http://aidbox.app/fhir/Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
request:
method: POST
url: Patient/cc95822b-ed0d-4e6a-ad48-358d029d8c61
response:
status: '201'
- fullUrl: http://aidbox.app/fhir/Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
request:
method: POST
url: Patient/36df7d8f-1a03-4073-8435-6741cdba90e9
response:
status: '201'

Delete Subscription - DELETE /fhir/Subscription/[id]

Delete Subscription resource.

Result:

Parameter
Type
Description
resource
object
Deleted Subscription resource.
Request
Response
DELETE /fhir/Subscription/subscription-patient-test-1
Status: 200
{
"meta": {
"profile": [
"http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
],
"lastUpdated": "2023-09-06T07:15:30.481730Z",
"versionId": "746",
"extension": [
{
"url": "http://example.com/createdat",
"valueInstant": "2023-09-06T07:15:30.481730Z"
}
]
},
"criteria": "http://aidbox.app/SubscriptionTopic/patient-test-1",
"channel": {
"type": "rest-hook",
"payload": "application/fhir+json",
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
"valueUnsignedInt": 1
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
"valuePositiveInt": 2
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
"valueUnsignedInt": 60
}
],
"_payload": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
"valueCode": "id-only"
}
]
},
"endpoint": "http://localhost:27193/patient-test-1"
},
"resourceType": "Subscription",
"reason": "R4/B Test Topic-Based Subscription for Patient resources",
"status": "active",
"id": "subscription-patient-test-1",
"end": "2020-12-31T12:00:00Z"
}