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[]
Extension URL:
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription​
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:
​filterCriteria​
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:
​heartbeatPeriod​
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
​Notification content level.

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
​http://terminology.hl7.org/CodeSystem/subscription-channel-type​
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"
}

Parameter	Type	Description
meta	object
meta.profile	string[]	Extension URL: http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
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: filterCriteria	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: heartbeatPeriod	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	Notification content level. 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	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	http://terminology.hl7.org/CodeSystem/subscription-channel-type
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.

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).

Parameter	Type	Description
resource	object	Deleted Subscription resource.

Last modified 1mo ago

Subscription API

Create Subscription - `POST /fhir/Subscription`

Params:

Result:

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

Params:

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

Params:

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

Result: