Event Streams

Type	Base Path	Trigger Name
Limited REST resource	~{realm}/event-streams/	N/A
Server-Sent Event resource	~{realm}/event-streams/{id}/stream	N/A

Server-sent events is a way to be notified about entity updates in real-time, whithout having to poll the resources of interest continiously. See also Triggers for an alternative way to receive notifications when entities are updates.

The event stream resource is view of the server's all active change data streams that is made to look like a normal REST resource. However, a couple of things is different from other REST resources:

• The ID is a string of random characters, not a sequence number. This is because the ID is also used as a secret access token.
• Once an entity has been deleted, it's truly gone and cannot be resurrected. Thus, point-in-time queries are not applicable to this resource, the d query parameter cannot be used to fetch a deleted entity and the deleted property does not exist.
• Extended properties are not available.
• listEventStreams does not support query filters or offset/count parameters.
• Event streams are automatically garbage-collected when no longer in use.
• The actual SSE resources only supports JSON-encoded events in the stream stream. XML or CSV is not supported.

Endpoints

Name	Method	Relative Path	Payload	Response	Description
addEventStream	POST	~{realm}/event-streams	EventStream	Stored_EventStream	Adds a new event stream to the list.
listEventStreams	GET	~{realm}/event-streams	N/A	Stored_EventStream[]	Retrieves a list of event streams.
getEventStream	GET	~{realm}/event-streams/{id	N/A	Stored_EventStream	Retrieves an event stream.
putEventStream	PUT	~{realm}/event-streams/{id	EventStream	Stored_EventStream	Replaces an event stream.
updateEventStream	PATCH	~{realm}/event-streams/{id	EventStream	Stored_EventStream	Updates specified event stream fields.
removeEventStream	DELETE	~{realm}/event-streams/{id}	N/A	N/A	Deletes an event stream.
openEventStream	GET	~{realm}/event-streams/{id}/stream	N/A	DataObjectOperation[]	The actual text/event-stream stream of DataObjectOperation objects.

Permissions

Permission	Description
edit-event-streams	Client is allowed to add new event streams and to modify or delete existing event streams.
show-event-streams	Client is allowed to query the trigger list and to fetch individual event streams.
use-event-streams	Client is allowed to create and look up individual event streams.

Note that:

1. In addition to the permissions above, when setting up an event stream, you also need read access to the actual resource from where events are streamed.
2. The actual text/event-stream resource does not require any authentication what-so-ever, since EventSource cannot send custom authentication headers. Because of this, the event stream ID should be considered a secret and is not to be exposed in any way by the client; also, once an event stream has been opened, its ID cannot be reused.

Entities

Interface EventStream

namespace EventStream {
    type State = 'pending' | 'active';
}

interface EventStream {
    'id'?: string;
    'created'?: DateTime;
    'updated'?: DateTime;
    'updated-by'?: number;
    'updated-from'?: number;
    'state': EventStream.State;
    'queries': QueryTrigger[];
    'location'?: number;
    'client'?: number;
    'user'?: number;
}

Property	Data Type	Description
id	String?	The event stream ID of this entity.
created	DateTime?	Date and time when this event stream was first created.
updated	DateTime?	Date and time when this event stream was last modified. Note: This is an approximation and could be off by up to a minute.
updated-by	Int64?	ID of User who last modified this event stream.
updated-from	Int64?	ID of Till (trusted device) which last modified this event stream.
state	EventStream.State	The current state of this event stream. active means a client is connected and listening for events.
queries	QueryTrigger[]	A list of query objects that specifies what events to stream.
location	Int64?	The location from where this event stream was created.
client	Int64?	The Till (trusted device) that created the event stream.
user	Int64?	The User who created the event stream.