Set versioned layer-level notifications

Layer-level notifications allow you to get a notification whenever changes occur in a particular layer. You can choose which changes you receive notifications for, including:

• All changes in the layer
• Changes to a geographic area
• Changes to specific partitions

Notifications are essentially a data stream. Notifications are written as messages to a stream layer, and 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. You can subscribe to either a few versioned layers in a catalog or all its layers. You can also configure subscription area and notification type to be either same or different for every layer that is being subscribed to.

When you create a subscription you can indicate which changes you want to be notified about. The procedures for creating each type of subscription is described in the following sections. Use the notification API to create a subscription. Regardless of which type of subscription you want to create, you must specify these parameters:

• The <Source Catalog HRN> portion of the API path is the HERE resource name (HRN) of the catalog that contains the layer for which you want to receive notifications.
• The layerIds parameter is the ID of the layer for which you want to receive notifications. You must specify at least one layer.
• The notificationCatalogHRN parameter is the HERE resource name (HRN) of the catalog that contains the stream layer to which the notification messages are written.
• The notificationStreamLayerID parameter is the ID of the stream layer to which the notification messages are written. This stream layer should 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 for multiple subscriptions.
• The subecriptionResultType field specifies the level of detail included in notification messages. Accepted values are SHORT, LIST, or FULL. If you do not specify subscriptionResultType, the default value of FULL is used.

Subscribing to notifications for the entire layer

When you want to receive a notification for any change to the layer, you subscribe to notifications for all partitions in the layer. To enable notifications for all partitions, in the body of the request specify all in the subscriptionType field.

POST /notification/v2/catalogs/<Source Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "<Layer to subscribe to>"
            ],
            "subscriptionArea": {
                "subscriptionType": "all"
            },
            "subscriptionResultType": "<Level of detail to include in the notifications - SHORT, LIST, or FULL>"
        }
    ],
    "notificationCatalogHRN": "<The HRN of the catalog that will contain the notification stream>",
    "notificationStreamLayerId": "<The stream layer ID to contain the notification stream>"
}

For example:

POST /notification/v2/catalogs/<Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "baseline_load"
            ],
            "subscriptionArea": {
                "subscriptionType": "all"
            },
            "subscriptionResultType": "FULL"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}

curl -X POST https://<Hostname for the notification API from the API Lookup Service>/notification/v2/catalogs/<Catalog HRN>/subscriptions \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Content-Type: application/json' \
-H 'Cache-Control: no-cache' \
-d '{
    "attributes": [
        {
            "layerIds": [
                "baseline_load"
            ],
            "subscriptionArea": {
                "subscriptionType": "all"
            },
            "subscriptionResultType": "FULL"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}'

Subscribing to notifications for a geographic area

To enable notifications for a geographic area in the layer, use these parameters in the body of the request to specify the geographic area of interest:

• In the subscriptionType parameter, specify wkt.
• In the wkt parameter, and specify a Well-Known Text (WKT) geometry object.

Any changes to the partitions that belong to the geographic area you specify will trigger a notification. Note that the precision is similar to enabling notifications for specific partitions because internally, geographic area is converted to HERE Tile partitions.

POST /notification/v2/catalogs/<Source Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "<Layer to subscribe to>"
            ],
            "subscriptionArea": {
                "subscriptionType": "wkt",
                "wkt": "<Well-Known Text (WKT) Geometry Object>"
            },
            "subscriptionResultType": "<Level of detail to include in the notifications - SHORT, LIST, or FULL>"
        }
    ],
    "notificationCatalogHRN": "<The HRN of the catalog that will contain the notification stream>",
    "notificationStreamLayerId": "<The stream layer ID to contain the notification stream>"
}

For example:

POST /notification/v2/catalogs/<Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "my-layer"
            ],
            "subscriptionArea": {
                "subscriptionType": "wkt",
                "wkt": "POLYGON((-130.80754564763947 53.5992823604481,-59.08879564763947 53.5992823604481,-59.08879564763947 22.68538434109208,-130.80754564763947 22.68538434109208,-130.80754564763947 53.5992823604481))"
            },
            "subscriptionResultType": "SHORT"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}

curl -X POST https://<Hostname for the notification API from the API Lookup Service>/notification/v2/catalogs/<Catalog HRN>/subscriptions \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Content-Type: application/json' \
-H 'Cache-Control: no-cache' \
-d '{
    "attributes": [
        {
            "layerIds": [
                "my-layer"
            ],
            "subscriptionArea": {
                "subscriptionType": "wkt",
                "wkt": "POLYGON((-130.80754564763947 53.5992823604481,-59.08879564763947 53.5992823604481,-59.08879564763947 22.68538434109208,-130.80754564763947 22.68538434109208,-130.80754564763947 53.5992823604481))"
            },
            "subscriptionResultType": "SHORT"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}'

For complete information on using the notification API, see the API Reference.

Subscribing to notifications for specific partitions

When you subscribe to notifications for specific partitions, changes to the specified partitions, including all child partitions (tiles), will trigger a notification. To enable notifications for specific partitions, in the body of the request specify partitions in the subscriptionType field, and specify a list of partition IDs in the partitions field.

POST /notification/v2/catalogs/<Source Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "<Layer to subscribe to>"
            ],
            "subscriptionArea": {
                "subscriptionType": "partitions",
                "partitions": [<List of partition IDs to subscribe to>]
            },
            "subscriptionResultType": "<Level of detail to include in the notifications - SHORT, LIST, or FULL>"
        }
    ],
    "notificationCatalogHRN": "<The HRN of the catalog that will contain the notification stream>",
    "notificationStreamLayerId": "<The stream layer ID to contain the notification stream>"
}

For example:

POST /notification/v2/catalogs/<Catalog HRN>/subscriptions HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "attributes": [
        {
            "layerIds": [
                "baseline_load"
            ],
            "subscriptionArea": {
                "subscriptionType": "partitions",
                "partitions": ["67", "70", "73", "76"]
            },
            "subscriptionResultType": "FULL"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}

curl -X POST https://<Hostname for the notification API from the API Lookup Service>/notification/v2/catalogs/<Catalog HRN>/subscriptions \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Content-Type: application/json' \
-H 'Cache-Control: no-cache' \
-d '{
    "attributes": [
        {
            "layerIds": [
                "baseline_load"
            ],
            "subscriptionArea": {
                "subscriptionType": "partitions",
                "partitions": ["67", "70", "73", "76"]
            },
            "subscriptionResultType": "FULL"
        }
    ],
    "notificationCatalogHRN": "<Catalog HRN>",
    "notificationStreamLayerId": "notifications-stream"
}'

For complete information on using the notification API, see the API Reference.

Contents of notifications

The content of notification messages varies depending on whether the subscription is configured to return a SHORT, LIST, or FULL response.

Short notification

If the subscription was created with a subscriptionResultType value of SHORT, notifications contain basic information about the new catalog version. For example:

{
    "catalogHRN":"<Catalog HRN>",
    "catalogVersion":250836,
    "layerId":"my-layer",    
    "timestamp": 1529947152971,
    "subscriptionResultType": "SHORT"
}

List notification

If the subscription was created with a subscriptionResultType value of LIST, notifications contain a list of the partition IDs that changed and have a subscription enabled.

For example:

{
    "partitions": [
        "75767",
        "75743",
        "75765",
        "75741",
        "75773",
        "78473",
        "78472",
        "78475",
        "78497",
        "78474",
        "78496",
        "78499",
        "78498",
        "78505",
        "78504"
    ],
    "catalogHRN":"<Catalog HRN>",
    "layerId":"my-layer",    
    "catalogVersion": 19448,
    "timestamp": 1529697829081,
    "subscriptionResultType": "LIST"
}

Full notification

If the subscription was created with a subscriptionResultType value of FULL, notifications contain metadata for each partition that changed in the new catalog version.

For example:

{
    "catalogHRN":"<Catalog HRN>",
    "catalogVersion":250836,
    "layerId":"my-layer",    
    "partitions": [
        {
            "version": 250836,
            "partition": "309967227",
            "layer": "my-layer",
            "dataHandle": "30111521-919d-4e45-8e48-3b6eea0a66b7",
            "checksum":"a19946acbc6323bca24797e6892d53d510c2f88a",
            "deleted": false
        }
    ],
    "timestamp": 1529944456598,
    "subscriptionResultType": "FULL"
}

Receiving notifications

Because notification messages are written to a stream layer, receiving notifications is the same process as reading data from any stream layer in 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.

Disabling notifications

To disable notifications, delete the subscription by specifying the catalog and layer that contains the notifications.

To delete all subscriptions associated with a target catalog:

DELETE /notification/v2/catalogs/<HRN of the Target Catalog>/layers/<Layer ID of Notification Stream> HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "deleteAll": true
}

To delete specific subscriptions you specify the subscription IDs that you want to delete. The subscription ID was provided when you created a subscription. You can get a list of subscription IDs using the notification API. For more information, see the API Reference.

DELETE /notification/v2/catalogs/<HRN of the Target Catalog>/layers/<Layer ID of the Notification Stream> HTTP/1.1
Host: <Hostname for the notification API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
    "deleteAll": false,
    "subscriptionIds" : ["<List of subscription IDs to delete>"]
}