Info | ||
---|---|---|
| ||
The Node pico engine only supports the alternate encoding at this time. |
Description
The Sky Event API is used to raise events to the Kinetic Rules Engine (KRE)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. This concept enables personal event networks. The Sky API follows the Evented API specification. The API implements event signal URLs (ESLs).
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 (
. To work within KRE, the eci must be associated with a valid Kinetic Entity Number (KEN)<eci>
) - a token that is used by the system to identify the entity and channel for whom the event is being raised.
See Event Channels for details.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 (
number<eid>
) - a uniqueidentifier assigned by the
endpoint raising events to theevent generator for correlation purposes.
The endpointThe 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 schema scheme is either http
or https
.The domain name depends on the server processing the events. For Kynetx, the domain name is cs.kobj.net
. The HTTP call may be either a POST
or a GET
. POST
is preferred.
The path is encoded as follows:
Code Block |
---|
/sky/event/<eci>/<eid>/<domain>/<type> |
If <eid>
is not given, the engine will generate a random EIDyou choose to not provide an <eid>
in this form, you can supply none
.
Signaling Events
Endpoints raise events to KRE by making an HTTP call to the ESL. The HTTP call may be either a POST
or a GET
. POST
is preferred.
The following key-value pairs are used:
...
the event type. _name
is also accepted for this attribute.
...
Keys with a leading underscore are reserved. Attributes are encoded as key-value pairs in the usual way.
...
Code Block |
---|
/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 |
---|---|
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 as follows:
{“_domain” : “web”,
“_name” : “pageview”,
“urls” : [“http://www.exampley.com/foo/bar.html”,
“http://www.google.com/search”]
}
The key-value pairs are encoded as query string parameters if a GET
is used.
Asynchronous vs Synchronous Event Processing
When the _async
attribute is present and has the value 1, the event generator is signaling the event engine that events may be processed asynchronously and that no response is expected.
When events are processed synchronously, the results of the processing, either a JSON-encoded directive document or a JavaScript program is returned to the generator. Actions in KRL are responsible for creating the response.
If the generator (which may be another KRL rule) does not require a response, it can add the _aync
attribute to indicate that the rules engine can process the event asynchronously. The rules engine will return immediately and process the event in a separate thread. This is most useful when the end goal of the event processing is a side-effect, either to a persistent variable or some other Web API. The event:send()
action raises asynchronous events by default.
Alternate Encoding
To make it possible to use the Sky API in systems that use generalized Webhooks to perform callbacks, an alternate encoding is available. In the alternate encoding, the event domain and type may be put in the path of the ESL as following:
/sky/event/<eci>/<eid>/<domain>/<type>
If an ESL is encoded this way, and also specified the domain and type in the attributes (i.e. in the body of the POST), the attribute specification will override the path specification.
If you choose to not provide an <eid>
in this form, you can supply none
as the EID to force the engine to generate a unique EID for the event.
...
. For example, to send the attributes temperature
and node_id
, the JSON would appear as follows:
Code Block | ||
---|---|---|
| ||
{
"temperature": 67,
"node_id": "2392029d003a:1"
} |
Status
Active