Attribute Subscription Resource
Attribute subscription resource is used to retrieve attribute values and updates to those values sequentially through a subscription.
Attribute Subscription Resource is introduced in Structure 6.0. When working with an older version, use Value Resource.
To learn more about attributes, see Loading Attribute Values.
Subscriptions
A subscription represents an interest of a client code in a set of attributes for a set of rows in a particular forest. Just like when loading attributes through Value Resource, in order to create a subscription, you need:
- A forest specification (
forestSpec) for the displayed forest. - A list of row IDs for which the values should be loaded. Row IDs can be retrieved from Forest Resource before calling Value Resource.
- A list of attribute specifications. Some examples are given below and in the documentation for Value Resource.
The chosen rows and attributes of interest are called a "window". The subscription server keeps track of registered subscriptions and corresponding windows, and, upon requests, calculates the updated data for a window and sends the updates back to the client.
Attribute subscription is the preferred way to continuously receive attribute values. For a one-off download, it's better to use Value Resource.
Base URL
Base URL for Attribute Subscription Resource is: $baseUrl/rest/structure/2.0/attribute/subscription
In the following documentation we will simply write /attribute/subscription meaning the full base URL above.
Common Parameters and Data Structures
There are a number of parameters that are used repeatedly in multiple methods in the Attribute Subscription Resource.
Input Query Parameters
These are passed as a part of URL. Neither of them are required.
| Parameter Name | Type | Default | Meaning |
|---|---|---|---|
valuesUpdate | Boolean | false | Indicates whether a client desires to receive the updated values for the current or updated window. This typically implies that a request to load these values will be executed. |
valuesTimeout | Long | 1000ms | Indicates the maximum time (in milliseconds) the server will wait for the values to be calculated before responding to the client. Applies only if The default can be adjusted through Advanced Configuration and Dark Features. |
signature | Integer | 0 | Together, signature and version define the last point of synchronization with the updates from the server. In the first request, the client should use zeros or not use them at all. Each successful response will include an updated signature and version, which client code should use the next time in order to get only the values that have changed. |
version | Integer | 0 |
Data Structure: SubscriptionWindow
The SubscriptionWindow data structure represents a subscription window.
| Field | Type | Meaning |
|---|---|---|
forestSpec | Object: a forest specification, the same as in Forest Resource | Defines the forest for which the values will be loaded. |
rows | Array of Long numbers | Defines a list of rows to be loaded. |
attributes | Array of Objects: AttributeSpec | Defines a list of attributes to be loaded. |
Example:
{
"forestSpec": { "structureId": 1 },
"rows": [ 10, 15, 1, 27, 1001 ],
"attributes": [
{ "id": "summary", "format": "text" },
{ "id": "key", "format": "html" },
{
"id": "progress",
"format": "number",
"params": {
"basedOn": "timetracking",
"resolvedComplete": true,
"weightBy": "equal"
}
}
]
}Data Structure: SubscriptionData
The SubscriptionData data structure is sent back from most of the REST calls to the Attribute Subscription Resource.
| Field | Type | Meaning |
|---|---|---|
id | Integer | The unique ID of the subscription. |
window | SubscriptionWindow | The current (updated) window for the subscription. |
valuesUpdate | SubscriptionUpdate | An update for the current subscription. |
Data Structure: SubscriptionUpdate
A subscription update is returned as a part of SubscriptionData structure and carries the new values, versioning information, error information and loading progress information.
This structure is also used in the Poll Resource.
| Field | Type | Meaning |
|---|---|---|
id | Integer | The unique ID of the subscription. |
full | Boolean | If true, this is a "full" or "total" update, meaning that all old values are obsolete. If false, it is an incremental update and includes only the updated values. |
fromVersion | RestVersion | Contains signature and version that were used to request the update. |
version | RestVersion | Contains signature and version that should be used to request the next update. |
data | Array of Objects | Each object represents values for a particular attribute. |
data[i].attribute | AttributeSpec | Describes the attribute for which the values are provided. |
data[i].values | Object | A map from row IDs (represented as strings) to the attribute values. A value may take multiple forms – it could be a number, a text, a boolean, an array or an object. |
data[i].outdated | Array of Longs | Optional field that lists the values which are known to contain outdated values. (But the values are provided all the same, so that the client can show something while the updated values are being calculated.) |
stillLoading | Boolean | If true, not all of the requested values have been loaded. The client can retry the request some time later. |
inaccessibleRows | Array of Longs | Optional field that lists all requested rows that are not accessible by the user (for any reason). The client code should not continue requesting them. |
error | StructureError | An object containing error code and other diagnostics in case of a problem. |
attributeErrors | A list of Objects | An optional list of attribute-specific errors. |
Resource Methods
Create Subscription
POST /attribute/subscriptionQuery parameters | valuesUpdate, valuesTimeout | Allow immediately loading some values for the created subscription. |
|---|---|---|
| Input data | SubscriptionWindow | Passed as the request body, the window defines the subscription parameters. |
| Response | SubscriptionData | Contains the ID of the newly created subscription, the used window, and some values if they were requested. |
Retrieve Subscription or Values
GET /attribute/subscription/ID| Path parameters | ID | Identifies the subscription by ID. |
|---|---|---|
Query parameters | valuesUpdate, valuesTimeout | Allow immediately loading some values for the created subscription. |
signature, version | Identify the previous version of the values that the client has seen to get incremental updates. | |
skipLoading | A Boolean parameter: if true, then only the already calculated values will be loaded, without requesting the attribute subsystem to reload the values in the window. | |
| Response | SubscriptionData | Contains all the subscription data and value updates if they were requested. |
Update Subscription
Used to completely change the subscription's window.
PUT /attribute/subscription/ID| Path parameters | ID | Identifies the subscription by ID. |
|---|---|---|
Query parameters | valuesUpdate, valuesTimeout | Allow immediately loading some values for the updated subscription. |
signature, version | Identify the previous version of the values that the client has seen to get incremental updates. | |
| Input data | SubscriptionWindow | The updated subscription window. |
| Response | SubscriptionData | Contains all the subscription data and value updates if they were requested. |
Patch Subscription
Used to partially change the subscription's window. Only the fields mentioned in the input SubscriptionWindow object will be updated.
POST /attribute/subscription/ID/patch| Path parameters | ID | Identifies the subscription by ID. |
|---|---|---|
Query parameters | valuesUpdate, valuesTimeout | Allow immediately loading some values for the updated subscription. |
signature, version | Identify the previous version of the values that the client has seen to get incremental updates. | |
| Input data | SubscriptionWindow | The object with the parts of the subscription window that need to be updated. |
| Response | SubscriptionData | Contains all the subscription data and value updates if they were requested. |
Delete Subscription
DELETE /attribute/subscription/ID| Path parameters | ID | Identifies the subscription by ID. |
|---|---|---|
| Response | HTTP 200 | Simple response with no data. |
User Access
When a subscription is created, it is attached to the current user. Only this user will have access to the subscription.
Subscription Expiration and Caching
A subscription is considered a transient, cache-like object. It may be removed from the server at any time, even if the user has not requested it.
When a request is made about a subscription that no longer exists, the server responds with HTTP 404 error and an object describing the error in detail. The client code may decide to re-create a subscription at that point.