Subscription API
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.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[] | [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: | integer | Timeout in seconds to attempt notification delivery.
Default value: 30 | |
channel.extension: | 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: | string | ||
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. |
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'
This operation is used to get the current status information about a topic-based Subscription.
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
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.
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 resource.
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"
}
Last modified 1mo ago