Skip to content

SolarUser Event Hook API

Jump to bottom Edit New page
Matt Magoffin edited this page Jun 18, 2020 · 3 revisions

The SolarUser Event Hook API provides methods to manage execution of pre-defined services in response to events generated by SolarNetwork. Conceptually these hooks are like push notifications sent from SolarNetwork to your own applications.

Events

Events define what data is available to be used by hooks. Events all include a topic property that defines a unique category for the event. This category determines the type of event and what other properties will be available.

Hook invocation consideration

SolarNetwork does not make any guarantees as to when a hook service will be invoked after a given event has been generated, other than "eventually". In practice hooks will be invoked as quickly as possible, but you should not make any assumptions about their timing.

SolarNetwork does not make any guarantees on the order or concurrency of invoked hook services. Put another way, the hooks can be invoked in parallel and out of order with respect to the creation date of the events.

Any application making use of SolarNetwork events should keep these considerations in mind, and make sure its handling of the hook events is flexible enough to accomodate them.

Event types

Event Type Topic Description
Aggregate Updated Datum datum/agg/update Aggregate datum computation.

Aggregate Updated event

Aggregate Updated datum events are generated after SolarNetwork has computed an aggregate value for a specific node and source. Keep in mind that SolarNetwork might compute an aggregate datum many times, and thus post Aggregate Updated events with identical content many times. For example, if a node posts datum for a source every minute then over the course of a single hour SolarNetwork might recompute a single datum source's hourly aggregate datum many times because the hourly aggregate value is impacted by the changing raw source data.

SolarNetwork does not make any guarantees as to when it computes aggregate datum values, other than "eventually".

Property Type Description
topic String datum/agg/update
userId Number The unique ID of the user that owns the event hook.
hookId Number The unique ID of the event hook configuration that is handling the event.
nodeId Number The unique ID of the node the event relates to.
sourceId String The datum source ID the event relates to.
aggregationKey String The aggregation type that has been computed.
timestamp Number The start of the aggregation time period that has been computed, as milliseconds since the epoch.

The aggregationKey property will be one of the following supported aggregation types:

Key Description
h Hour time period, covering 60 minutes.
d Day time period, covering 24 hours.
M Month time period, covering a variable number of days based on the calendar month.

An example Aggregate Updated node source event, expressed as JSON, looks like this:

{
  "topic"          : "datum/agg/update",
  "userId"         : 123,
  "hookId"         : 234,
  "nodeId"         : 456,
  "sourceId"       : "/power/1",
  "aggregationKey" : "M",
  "timestamp"      : 1590926400000
}

Event hook services

The following hook services are available on SolarNetwork.

Service Description
SQS Publish events as JSON to an AWS Simple Queue Service queue.

SQS hook service

ID net.solarnetwork.central.user.event.dest.sqs.SqsUserNodeEventHookService

The SQS hook service publishes events as JSON objects to an AWS SQS queue. The queue must exist already for SolarNetwork to be able to publish events to it. The service supports the following settings:

Setting Type Description
region string The AWS region name the queue exists in. For example ap-southeast-2.
queueName string The name of the SQS queue to publish events to.
accessKey string The AWS access key to use for posting the events.
secretKey string The AWS secret key to use for posting the events.

⚠️ NOTE: the secretKey property is a secure setting and will be shown in API results as a digest value. When posting values you can omit this property to leave the value unchanged.

Here's an example serviceProperties object for the SQS hook service that could be used when posting a hook configuration:

{
  "region"    : "us-west-2",
  "queueName" : "node-event-dest-test",
  "accessKey" : "AAAAAAA555555555FFFF",
  "secretKey" : "super.secret.key.here"
}

Endpoints

All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens. Some endpoints return localized messages. See the localized setting specifiers section for more information.

Verb Endpoint Description
GET /user/event/node/hook/services List the available node-related hook services.
GET /user/event/node/hooks List the available node-related hook configurations.
POST /user/event/node/hooks Create or update node-related hook configurations.
GET /user/event/node/hooks/{id} View a specific node-related hook configuration.
DELETE /user/event/node/hooks/{id} Delete a specific node-related hook configuration.
GET /user/event/node/topics List the available node-related event topics.

Node hook services list

Lists the available node-related hook services.

GET /solaruser/api/v1/sec/user/event/node/hook/services

Node hook services list response

The response will be a list of localized event hook service objects. The objects have the following properties:

Property Type Description
id string The service unique identifier.
locale string The locale of the localized messages in the response.
localizedName string A localized name for the service.
localizedDescription string A localized description of the service.
settingSpecifiers array The configurable setting specifiers for the service.
localizedInfoMessages object Localized messages for the associated setting specifiers.

An example response looks like this:

{
  "success": true,
  "data": [
    {
      "id": "net.solarnetwork.central.user.event.dest.sqs.SqsUserNodeEventHookService",
      "locale": "en",
      "localizedName": "AWS Simple Queue Service (SQS) Node Event Hook Service",
      "localizedDescription": "Publish node events to an AWS SQS queue as JSON-formatted message objects.",
      "settingSpecifiers": [
        {
          "key": "region",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "queueName",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "accessKey",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "secretKey",
          "defaultValue": "",
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        }
      ],
      "localizedInfoMessages": {
        "region.key": "Region",
        "region.desc": "The SQS queue region to use. For example <code>us-west-2</code>.",
        "queueName.key": "Queue Name",
        "queueName.desc": "The SQS queue name to use. This queue must exist already.",
        "accessKey.key": "Access Key",
        "accessKey.desc": "The AWS access key to use for posting the event data.",
        "secretKey.key": "Secret Key",
        "secretKey.desc": "The AWS secret key to use for posting the event data."
      }
    }
  ]
}

Node hooks list

Lists the available node-related hook configurations.

GET /solaruser/api/v1/sec/user/event/node/hooks

Node hook configuration list response

The response will be a list of event hook objects. See Node hook view response for details.

Node hook save

Create or update a node-related hook configuration. To create a configuration omit the id property in the posted data. To update a configuration include the id property for the configuration you want to update. When updating, the provided object completely replaces the existing configuration so be sure to submit a complete configuration object.

POST /solaruser/api/v1/sec/user/event/node/hooks
id The ID of the hook configuration to update, or omit to create a new configuration.
name A name to give to the hook configuration.
topic The event topic the hook is for.
nodeIds An array of node IDs the hook is restricted to, or omit for all nodes owned by the requesting user.
sourceIds An array of source ID patterns the hook is restricted to, or null for all source IDs.
serviceIdentifier The ID of the node hook service to use.
serviceProperties An object with the settings for the hook service (service specific).

The response will be a the complete configuration object, including the unique id generated when creating the object. See Node hook view response for details.

Node hook view

View a specific node hook configuration object.

GET /solaruser/api/v1/sec/user/event/node/hooks/{id}
id The ID of the hook configuration to view.

Node hook view response

The response will be a node event hook object. The object will have the following properties:

Property Type Description
id number The Unique ID of the hook configuration.
userId number The Unique ID of the user that owns the event hook.
created string The date the hook was created, in RFC 3339 format yyyy-MM-dd HH:mm:ss.SSS'Z'.
name string A name given to the hook configuration.
topic string The event topic the hook is for.
nodeIds array An array of node IDs the hook is restricted to, or null for all nodes owned by userId.
sourceIds array An array of source ID patterns the hook is restricted to, or null for all source IDs.
serviceIdentifier string The ID of the node hook service to use.
serviceProperties object The settings for the hook service (service specific).

An example response looks like this:

{
  "success": true,
  "data": {
    "id": 1,
    "userId": 123,
    "created": "2020-06-16 03:04:04.82932Z",
    "name": "SQS Test",
    "topic": "datum/agg/update",
    "nodeIds": [
      234
    ],
    "sourceIds": [
      "/power/1"
    ],
    "serviceIdentifier": "net.solarnetwork.central.user.event.dest.sqs.SqsUserNodeEventHookService",
    "serviceProperties": {
      "region": "us-west-2",
      "accessKey": "AAAAAAA555555555FFFF",
      "queueName": "node-event-dest-test",
      "secretKey": "{SSHA-256}YRDfTtemkw5iMXETEjZVE4ANcQUJ/BDqDfUqbyiRGrZYvsWt+azABg=="
    }
  }
}

Node hook delete

Delete a specific node hook configuration object.

DELETE /solaruser/api/v1/sec/user/event/node/hooks/{id}
id The ID of the hook configuration to delete.

Node event topics list

Lists the available node-related event topics that can be configured on event hooks.

GET /solaruser/api/v1/sec/user/event/node/topics

Node event topics list response

The response will be a list of localized event topic descriptor objects. The objects have the following properties:

Property Type Description
id string The unique topic name.
locale string The locale used for the localized description values.
localizedName string A localized friendly name for the event topic.
localizedDescription string A localized description of the event topic, which may include basic HTML tags.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "datum/agg/update",
      "locale": "en",
      "localizedName": "Aggregate Updated",
      "localizedDescription": "Event triggered when SolarNetwork updates an aggregate value for a node source. The event message includes <code>timestamp</code> and <code>aggregationKey</code> properties that reveal which aggregate datum was affected."
    }
  ]
}
Add a custom footer
Clone this wiki locally