# Subscription APIs
The Subscription APIs (sometimes called the Hot Path APIs) allow your apps to get close to real-time updates on your data. There are four types of subscriptions:
- platform events - deliver information about what's happening with various entities in the Platform (e.g. object models, type definitions, model definitions). For example, you could use it to track all occurrences of some objects being updated/created.
- variables - allow you to get the latest values for your time-series variable values. You could use it to draw a close to the real-time graph of changes to some variable data in your system.
- events - similar to variables, but deliver events instead.
- alarms - similar to variables, but deliver alarms instead.
Each of these subscription types has a similar request schema. Each of them
requires a filter to be defined. Thanks to it you can limit the information
being delivered to you to only focus on the data that is interesting in your
case (e.g. you could subscribe to variable data updates of one specific object
instance only). The filter should follow the QEL
schema.
Code Examples
You can find code examples of how to use the Hot Path API here.
# POST Create a Subscription to a Platform Event Topic
AMQP 1.0 compatible
# /subscriptions/platformEvents
# Description
Filterable properties:
eventType: string, eventTime: dateTime, severity:
string + event type specific properties
# Request Payload
This API endpoint expects the following fields in the JSON payload:
| Name | Description | Required | Data Type |
|---|---|---|---|
| subscriptionTTL | Subscription Time-to-live is minutes. This property directly refers to the idle time of the subscription. If there is no data being sent to the subscription and there are no clients connected to the subscription, then it will automatically be deleted once this time expires. The value must be in the range of 5-43200 (max 30 days). It should be greater than the value of sasTokenTTL. | Yes | number |
| sasTokenTTL | Azure SAS Token Time-to-live is minutes. The minimum value is 5. | Yes | number |
| filter | Subscription filter. | Yes | string |
# Response Payload
This API endpoint returns the following values for valid requests:
| Name | Description | Data Type |
|---|---|---|
| subscriptionId | The unique identifier of the created subscription | string |
| connectionURL | The URL that should be used to connect to the subscription feed | string |
| sasToken | The Azure SAS Token that should be used for authorization while connecting to the feed | string |
# Responses Codes
| Code | Description | Schema |
|---|---|---|
| 201 | Subscription was created successfully. | SubscriptionResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Create a Subscription to a Variable Topic
AMQP 1.0 compatible
# /subscriptions/variables
# Description
Filterable properties:
objectId: string, model: string, variable: string,
timestamp: dateTime, quality: number
# Request Payload
This API endpoint expects the following fields in the JSON payload:
| Name | Description | Required | Data Type |
|---|---|---|---|
| subscriptionTTL | Subscription Time-to-live is minutes. This property directly refers to the idle time of the subscription. If there is no data being sent to the subscription and there are no clients connected to the subscription, then it will automatically be deleted once this time expires. The value must be in the range of 5-43200 (max 30 days). It should be greater than the value of sasTokenTTL. | Yes | number |
| sasTokenTTL | Azure SAS Token Time-to-live is minutes. The minimum value is 5. | Yes | number |
| filter | Subscription filter. | Yes | string |
# Response Payload
This API endpoint returns the following values for valid requests:
| Name | Description | Data Type |
|---|---|---|
| subscriptionId | The unique identifier of the created subscription | string |
| connectionURL | The URL that should be used to connect to the subscription feed | string |
| sasToken | The Azure SAS Token that should be used for authorization while connecting to the feed | string |
# Responses Codes
| Code | Description | Schema |
|---|---|---|
| 201 | Subscription was created successfully. | SubscriptionResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Create a Subscription to an Alarms Topic
AMQP 1.0 compatible
# /subscriptions/alarms
# Description
Filterable properties:
objectId: string, model: string, alarm: string,
timestamp: dateTime
# Request Payload
This API endpoint expects the following fields in the JSON payload:
| Name | Description | Required | Data Type |
|---|---|---|---|
| subscriptionTTL | Subscription Time-to-live is minutes. This property directly refers to the idle time of the subscription. If there is no data being sent to the subscription and there are no clients connected to the subscription, then it will automatically be deleted once this time expires. The value must be in the range of 5-43200 (max 30 days). It should be greater than the value of sasTokenTTL. | Yes | number |
| sasTokenTTL | Azure SAS Token Time-to-live is minutes. The minimum value is 5. | Yes | number |
| filter | Subscription filter. | Yes | string |
# Response Payload
This API endpoint returns the following values for valid requests:
| Name | Description | Data Type |
|---|---|---|
| subscriptionId | The unique identifier of the created subscription | string |
| connectionURL | The URL that should be used to connect to the subscription feed | string |
| sasToken | The Azure SAS Token that should be used for authorization while connecting to the feed | string |
# Responses Codes
| Code | Description | Schema |
|---|---|---|
| 201 | Subscription was created successfully. | SubscriptionResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# POST Create a Subscription to an Event Topic
AMQP 1.0 compatible
# /subscriptions/events
# Description
Filterable properties:
objectId: string, model: string, event: string,
timestamp: dateTime
# Request Payload
This API endpoint expects the following fields in the JSON payload:
| Name | Description | Required | Data Type |
|---|---|---|---|
| subscriptionTTL | Subscription Time-to-live is minutes. This property directly refers to the idle time of the subscription. If there is no data being sent to the subscription and there are no clients connected to the subscription, then it will automatically be deleted once this time expires. The value must be in the range of 5-43200 (max 30 days). It should be greater than the value of sasTokenTTL. | Yes | number |
| sasTokenTTL | Azure SAS Token Time-to-live is minutes. The minimum value is 5. | Yes | number |
| filter | Subscription filter. | Yes | string |
# Response Payload
This API endpoint returns the following values for valid requests:
| Name | Description | Data Type |
|---|---|---|
| subscriptionId | The unique identifier of the created subscription | string |
| connectionURL | The URL that should be used to connect to the subscription feed | string |
| sasToken | The Azure SAS Token that should be used for authorization while connecting to the feed | string |
# Responses Codes
| Code | Description | Schema |
|---|---|---|
| 201 | Subscription was created successfully. | SubscriptionResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# PUT Generate a New Token for a Subscription
# /subscriptions/{type}/{subscriptionId}
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| type | path | Subscription type | Yes | SubscriptionTypes |
| subscriptionId | path | Existing subscription identifier | Yes | string |
# Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Success | SubscriptionUpdatedResponse |
| 400 | Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc | ServiceErrors |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | Subscription with this id was not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
# DELETE Delete a Subscription
# /subscriptions/{type}/{subscriptionId}
# Parameters
| Name | Located in | Description | Required | Schema |
|---|---|---|---|---|
| type | path | Subscription type | Yes | SubscriptionTypes |
| subscriptionId | path | Existing subscription identifier | Yes | string |
# Responses
| Code | Description | Schema |
|---|---|---|
| 204 | Success | |
| 401 | Not Authorized. Either the Access token is missing or the access token validation failed | |
| 403 | Access Forbidden. Requesting entity does not have enough permissions to access the resource | |
| 404 | Subscription with this id was not found | ServiceErrors |
| 429 | Too many requests - indicates the user has sent too many requests in a given amount of time | ServiceErrors |
| 500 | Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors | ServiceErrors |
← Storage Applications →