events

Discovery Link

mandatory

Link that locates the events management service URI space. Resources that represent event s collected for the currently available events subscriptions are located as sub resources of the events resource.

subscriptions

Discovery Link

mandatory

Link that locates the subscription management service URI space. Resources that represent created event subscriptions are located as sub resources of the subscriptions resource.

GET

/m2m/[<gatewayID>]/re

Retrieves the representation of the Base Resource which contains a collection of references for the base event and subscription management sub resources registered in the system. If the representation is to be acquired for a specific OSGi service gateway then gateway identifier needs to be provided either explicitly in the URL or implicitly via session cookie or X-Gateway-Identifier header.

GET

/m2m/[<gatewayID>]/re/version

Retrieves the representation of the Version Resource of the events and subscriptions management service. If the versioning information is requested for a specific OSGi service gateway then the gateway identifier can be provider either explicitly in the URI or implicitly via session cookie or X-Gateway-Identifier header.

criteria

Event Subscription Criterion Description[]

optional

Collection of event filtering criteria entities. Clients that wish to subscribe for events and receive event notifications of interest must specify a filtering criteria in the subscription which is based on event topics and optional LDAP filter defined over the event properties. [GET]

href

Link

mandatory

Reference to this subscription resource. URIs for access and modification of other sub resources in the subscription resource's URI space can easily be derived by appending the field name to the self link. [GET]

gatewayId

Identifier

optional

Unique identifier of the gateway that this subscription has been created for, if there is such. If this subscription is not scoped to a creation gateway or has been created via the local REST web services running on the Bosch IoT Gateway Software then this field is omitted. [GET] [POST]

id

Identifier

mandatory

Unique subscription identifier generated at the time a subscription is created. [GET]

topics

Sting[]

optional

Collection of one or more event topic of interest. [GET] [POST]

filter

Sting

optional

LDAP filter string that filters out some of the events. The filter keys can match the properties of the events of interest. [GET] [POST]

POST

/m2m/[<gatewayID>]/re/subscriptions

X-Gateway-Identifier

Creates an event subscription resource in the system based on the Event Subscription Resource representation included in the request message body. The Event Subscription Resource representation may include all of the mandatory and any of the optional fields annotated with [POST]. On successful creation, the response shall include Location header identifying the URI of the newly created subscription resource which full representation shall be included in the response message body. If the subscription is to be created for a certain OSGi service gateway then the gateway identifier can be provided either explicitly in the URI or implicitly via session cookie or X-Gateway-Identifier HTTP request header.

DELETE

/m2m/[<gatewayID>]/re/subscriptions/<subscriptionID>

X-Gateway-Identifier

Removes the event subscription with identifier <subscriptionID>. If the event subscription has been created on a certain OSGi service gateway then the gateway identifier can be provided either explicitly in the URI or implicitly via session cookie or X-Gateway-Identifier HTTP request header.

GET

/m2m/[<gatewayID>]/re/subscriptions/<subscriptionID>

X-Gateway-Identifier

Retrieves the Event Subscription Resource representation of event subscription with identifier <subscriptionID>. The Event Subscription Resource representation shall include all of the mandatory and any of the optional fields annotated with [GET]. If the event subscription has been created on certain OSGi service gateway then the gateway identifier can be provided either explicitly in the URI or implicitly via the session cookie or X-Gateway-Identifier HTTP request header.

entries

Event Resource []

optional

Collection of Event Resource representations that satisfy the filtering and limitation constraints given as query parameters. In case there are no events to satisfy the constraints then this field is omitted. [GET]

href

Link

mandatory

Self link to this resource. URIs for querying and filtering of the collection of events represented by this resource can easily be derived by appending query parameters to this link. [GET]

properties

Map<String, Object>

mandatory

Event properties. Keys are string and values may be any serializable type which implies java primitive types, primitive wrapper classes, strings, java bean classes and JAXB elements. Any of the properties except for links can be used to construct a LDAP filter for event subscriptions. In general, event property fields reflect the fields of the resource which state change has triggered the event. [GET]

topic

String

mandatory

Event topic identifying the event type of interest. Can be used in event subscriptions. [GET]

GET

/m2m/[<gatewayID>]/re/events/<subscriptionID>

timeout

X-Gateway-Identifier

Retrieves Event Collection Resource representing currently available notifications that have matched the event topics and filters defined for subscription with identifier <subscriptionID>. The Event Collection Resource representations shall include all of the mandatory and any of the optional fields annotated with [GET]. The list will contain all events that have appeared since the last retrieval or since the subscription has been created, in case GET is called for the first time. If there are any events available at the time the request is performed then an instant response containing all available events will be sent to the client. If there are no currently available events at the time then the behavior of the server depends on the presence of the <timeout> query parameter which defines a timeout in milliseconds to block until events are available. If <timeout> query parameter is missing when the call is performed then an instant response will be sent to the client containing an empty list. If <timeout> parameter is present then the request will be blocked until events becomes available or the defined timeout expires.In case the blocking timeout has expired and no events matching the subscription have been generated then the response will again contain an empty list. If the subscription is to be scoped to a certain OSGi service gateway then the gateway identifier can be provided either explicitly in the filter or URI or implicitly via session cookie or X-Gateway-Identifier HTTP header.

50401 Event Subscription Not Found

Identifies that the operation over the representation of a particular resource located in the name space of the Remote Events Management RESTful web service cannot be performed by the server due to the resource being associated with an event subscription which does not exist or cannot be found by the server.

50400 Events Management Service Unavailable

Identifies that the operation over the representation of a particular resource located in the name space of the Remote Events Management RESTful web service cannot be performed by the server due to unavailability of the underlying Events Management service.

50103 Illegal Event Subscription Criteria

Identifies that the operation over the representations of particular resources located in the name space of the Remote Events Management RESTful web service cannot be performed by the server due to the resource representation transferred by the client containing an illegal event subscription criteria, e.g. event subscription resource representation transferred by the client for is missing a subscription criteria or the criteria is an empty array.

50402 Illegal Event Subscription Identifier

Identifies that the operation over the representations of particular resources located in the name space of the Remote Events Management RESTful web service cannot be performed by the server due to the resource representation transferred by the client containing an illegal event subscription identifier, e.g. missing or an empty string.