Catalog-Level Notification

When notification is enabled for a catalog, a stream is created with the same HERE Resource Name (HRN) as the catalog. Whenever the catalog data is updated, a new record is written to the stream. This notification record contains the timestamp of the change and the new catalog version number. The version number is particularly useful since you can use it to know which catalog version to request to get the updated data.

Enable Notifications

To enable catalog-level notification, use the config API to set enabled in the notifications object to true as shown in this example:

POST /<Base path for the config API from the API Lookup Service>/catalogs HTTP/1.1
Host: <Hostname for the config API from the API Lookup Service>
Content-Type: application/json
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

{
  "id": "my-catalog",
  "name": "My Catalog",
  "summary": "This catalog contains my data.",
  "description": "The catalog provides aggregated information about my data, including the type and location of each item, status, start and end time, and other relevant data.",
  "layers": [
    ...
  ],
  "version": 1,
  "notifications": {
    "enabled": true
  }
}

You can enable notifications when creating a catalog (POST) and when updating a catalog (PUT).

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

Subscribe to Notifications

To subscribe to a notification stream, use the Data Client Library.

If you are unsure if notifications are enabled for the catalog, use the config API to get the catalog's configuration details. In the notifications object, if enabled is set to true then notifications are enabled for the catalog.

When you receive a notification, it will contain the new version of the catalog as well as the time stamp, in epoch seconds, when the change occurred:

{
  "catalogVersion":874,
  "zonedDateTime":1521683573.315000000
}

Note

If there is an error that prevents notifications from being written to the notification stream, you may see a gap in the sequence of notifications. For example, if there is an error and notifications are not available while the catalog is updated to versions 5, 6, and 7, you will only receive a notification for version 7. Be sure to account for this possibility in your code.

results matching ""

    No results matching ""