Sky Event API

Description

The Sky Event API is used to raise events to the pico engine. Because the Sky API has the concept of unique entity identity built into the API, each event raised using the Sky API is raised on behalf of a particular entity.

For a thorough tutorial of the use of the Sky Event API with the Pico Engine read the Events and Queries Lesson.

Event Schema

The event schema includes the following components:

  • channel identifier (<eci>) - a token that is used by the system to identify the entity and channel for whom the event is being raised.

  • event domain - the namespace for any given event

  • event type - the individual events within the namespace. The word name is often used interchangably with type in this documentation and elsewhere. 

  • attributes - any given event may include attributes that further define the event

  • event ID  (<eid>) - a unique identifier assigned by the event generator for correlation purposes. The event generator is free to make the <eid> any value so long as it is URL encoded. The primary use of the correlation identifier is in examining log files.

Event Signal URL (ESL)

The components of the event are encoded in an event signal URL as follows:

The scheme is either http or https. The HTTP call may be either a POST or a GETPOST is preferred.

The path is encoded as follows:

/sky/event/<eci>/<eid>/<domain>/<type>

If you choose to not provide an <eid> in this form, you can supply none.  

/sky/event/<eci>/none/<domain>/<type>

Attributes

When the event is raised using an HTTP POST, attributes are sent as the body. These parameters must be encoded using one of the methods shown in the following table. Note that the Content-Type header must be set to the appropriate mime-type for the event consumer to understand the message.

encoding

mime-type

encoding

mime-type

form

application/x-www-form-urlencoded

JSON

application/json

If the body is JSON-encoded, the encoding should be a JSON object containing the keys and values. For example, to send the attributes temperature and node_id, the JSON would appear as follows:

{ "temperature": 67, "node_id": "2392029d003a:1" }

Status 

Active

Copyright Picolabs | Licensed under Creative Commons.