Set interactive map layer-level notifications

Notifications are essentially a data stream to receive updates about feature changes in an interactive map layer.
Notifications are written as messages to a stream layer. You receive notifications by subscribing to the layer and consuming the messages as you would consume data from any stream layer in the HERE platform. You can create multiple subscriptions for a catalog, but a subscription always pertains to a single catalog.

The content of notification messages varies depending on which type of subscription is created. The following are three types of supported subscriptions:

• perFeature
• perTransaction
• contentChange

Creating a subscription

The procedures for creating each type of subscription using the subscription API are described in the following sections. Regardless of which type of subscription you want to create, you must specify the following required parameters:

Required parameters:

• <subscription name> - The name of the subscription.
• <subscription type> - The type of subscription, which also specifies the level of detail included in notification messages. Possible values include perTransaction,perFeature and contentChange.
• <source catalog HRN> - HERE Resource Name (HRN) of the catalog that contains the layer from which you want to receive notifications.
• <source layer ID> - The ID of the layer from which you want to receive notifications.
• <destination catalog HRN> - The HERE Resource Name (HRN) of the catalog that contains the stream layer to which notification messages are written.
• <destination layer ID> - The ID of the stream layer to which notification messages are written. This stream layer must already exist. You must either have created the stream layer or you must have permissions to READ and WRITE to this layer. The stream layer can be in the same catalog as the layer for which you want to receive notifications. A stream layer can be reused across multiple subscriptions.

Optional parameters:

• <subscription description>- A detailed description of the subscription.

POST /config/v1/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
x-idempotency-key: <Unique value generated by client>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
  "subscriptionName": "<subscription name>",
  "description": "<subscription description>",
  "sourceCatalog": "<source catalog HRN>",
  "sourceLayer": "<source layer ID>",
  "destinationCatalog": "<destination catalog HRN>",
  "destinationLayer": "<destination layer ID>",
  "interactiveMapSubscription": {
    "type": "<subscription name>"
  }
}

For example:

POST /config/v1/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
x-idempotency-key: <Unique value generated by client>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
"subscriptionName": "my-subscription",
"description": "string",
"sourceCatalog": "hrn:here-cn:data::olp-cn-here:my-source-catalog",
"sourceLayer": "source-layer",
"destinationCatalog": "hrn:here-cn:data::olp-cn-here:my-destination-catalog",
"destinationLayer": "destination-layer",
"interactiveMapSubscription": {
"type": "perFeature"
}
}

curl -X POST https://<Hostname for the subscription API>/config/v1/subscriptions \
-H 'x-idempotency-key: <Unique value generated by client> \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Content-Type: application/json' \
-H 'Cache-Control: no-cache' \
-d '{
"subscriptionName": "my-subscription",
"description": "string",
"sourceCatalog": "hrn:here-cn:data::olp-cn-here:my-source-catalog",
"sourceLayer": "source-layer",
"destinationCatalog": "hrn:here-cn:data::olp-cn-here:my-destination-catalog",
"destinationLayer": "destination-layer",
"interactiveMapSubscription": {
"type": "perFeature"
}
}'

Listing all subscriptions

To get the list of all the subscriptions that your App has read access to, use the following request:

GET /config/v1/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>

For example:

GET /config/v1/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>

curl -X GET https://<Hostname for the notification API from the API Lookup Service>/config/v1/subscriptions \
-H 'Authorization: Bearer <Authorization Token>' \

Get subscription configuration

To get the detailed configuration of a subscription, specify the <subscriptionHrn> that you want to read. The <subscriptionHrn> was provided when you created the subscription or from the list of subscriptions.

GET /config/v1/subscriptions/{subscriptionHrn} HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>

For example:

GET /config/v1/subscriptions/{subscriptionHrn} HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>

curl -X GET https://<Hostname for the notification API from the API Lookup Service>/config/v1/subscriptions/hrn:here-cn:data-subscription::olp-cn-here:my-subscription-7d93563980d94f1b \
-H 'Authorization: Bearer <Authorization Token>' \

Deleting a subscription

To delete a subscription, specify the <subscriptionHrn> that you want to delete. The <subscriptionHrn> was provided when you created the subscription or from the list of subscriptions.

DELETE /config/v1/subscriptions/{subscriptionHrn} HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
x-idempotency-key: <Unique value generated by client>
Authorization: Bearer <Authorization Token>

For example:

DELETE /config/v1/subscriptions/hrn:here-cn:data-subscription::olp-cn-here:my-subscription-7d93563980d94f1b HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
x-idempotency-key: <Unique value generated by client>
Authorization: Bearer <Authorization Token>

curl -X DELETE https://<Hostname for the notification API from the API Lookup Service>/config/v1/subscriptions/hrn:cn-here:data-subscription::olp-cn-here:my-subscription-7d93563980d94f1b \
-H 'Authorization: Bearer <Authorization Token>' \

Types of subscriptions

perFeature

If a subscription is created with a type value of perFeature, then notifications contain basic information about the specific feature changed in the source layer. For example:

{
  "type": "FeatureChange",
  "operation": <"INSERT"|"DELETE"|"UPDATE">,
  "catalogHrn": "hrn:here-cn:data::realm:source-catalog",
  "layerId": "source-iml",
  "feature": {
    "type": "Feature", ...
  }
}

perTransaction

If a subscription was created with the type value of perTransaction, then notifications contain FeatureCollection, with all the features changed as a single transaction in the source layer. For example:

For example:

{
  "type": "Changeset",
  "version": 5,
  "author": "abcXyz",
  "catalogHrn": "hrn:here-cn:data::realm:source-catalog",
  "layerId": "source-iml",
  "createdAt": 1668519747712,
  "inserted": {
    "type": "FeatureCollection",
    "features": [...
    ]
  },
  "updated": {
    "type": "FeatureCollection",
    "features": [...
    ]
  },
  "deleted": {
    "type": "FeatureCollection",
    "features": [...
    ]
  }
}

contentChange

If a subscription is created with the type value of contentChange, then a simple notification is sent to indicate that there has been some feature(s) changed in the source layer. For example:

For example:

{
  "type": "ChangeNotification",
  "catalogHrn": "hrn:here-cn:data::realm:source-catalog",
  "layerId": "source-iml",
  "createdAt": 1668519747712
}

Receiving notifications

Notification messages are written to a stream layer, therefore receiving notifications follows the same process as reading data from any stream layer on the HERE platform. There are two ways of reading notifications messages from a stream layer:

• Use the Data Client Library. For more information about reading data from a stream layer using the Data Client Library, see the Data Client Library Developer Guide.
• Use the stream API. For more information about reading data from a stream layer using the stream API, see the Data API's API Reference. ```