Overview
The events interface consists of three parts:
- The event API resource returns URIs and URI templates to collections of events, so that all events or events of a specified type and/or a specific source device can be retrieved.
- The event collection resource retrieves events and enables creating new events.
- The event resource represents individual events that can be queried and deleted.
Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.
Events API
EventAPI [application/vnd.com.nsn.cumulocity.eventApi+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URL linking to this resource. |
events | EventCollection | 1 | Collection of all events. |
eventsForType | EventCollection URI template | 1 | Read-only collection of all events of a particular type (placeholder {type}). |
eventsForSource | EventCollection URI template | 1 | Read-only collection of all events from a particular source object (placeholder {source}). |
eventsForSourceAndType | EventCollection URI template | 1 | Read-only collection of all events of a particular type and from a particular source (placeholders {type} and {source}). |
eventsForTime | EventCollection URI template | 1 | Read-only collection of all events from a particular period (placeholder {dateFrom}, {dateTo}). |
eventsForFragmentType | EventCollection URI template | 1 | Read-only collection of all events containing a particular fragment type (placeholder {fragmentType}). |
eventsForSourceAndTime | EventCollection URI template | 1 | Read-only collection of all events from a particular source object from a particular period (placeholders {source}, {dateFrom}, {dateTo}). |
eventsForSourceAndFragmentType | EventCollection URI template | 1 | Read-only collection of all events of a particular source object containing a particular fragment type (placeholders {source}, {fragmentType}). |
eventsForDateAndFragmentType | EventCollection URI template | 1 | Read-only collection of all events from a particular period containing a particular fragment type (placeholders {dateFrom}, {dateTo}, {fragmentType}). |
eventsForFragmentTypeAndType | EventCollection URI template | 1 | Read-only collection of all events of a particular type containing a particular fragment type (placeholders {fragmentType}, {type}). |
eventsForTimeAndType | EventCollection URI template | 1 | Read-only collection of all events with a particular type from a particular period (placeholders {type}, {dateFrom}, {dateTo}). |
eventsForSourceAnd DateAndFragmentType | EventCollection URI template | 1 | Read-only collection of all events from a particular source object, containing a particular fragment type, from a particular period (placeholders {source}, {dateFrom}, {dateTo}, {fragmentType}). |
eventsForSourceAnd DateAndFragmentTypeAndType | EventCollection URI template | 1 | Read-only collection of all events from a particular source object, with a particular type, containing a particular fragment type, from a particular period (placeholders {source}, {dateFrom}, {dateTo}, {fragmentType}, {type}). |
eventsForSourceAnd FragmentTypeAndType | EventCollection URI template | 1 | Read-only collection of all events from a particular source object, with a particular type, containing a particular fragment type (placeholders {source}, {fragmentType}, {type}). |
eventsForSourceAndTimeAndType | EventCollection URI template | 1 | Read-only collection of all events from a particular source object, with a particular type, from a particular period (placeholders {source}, {type}, {dateFrom}, {dateTo}). |
eventsForDateAnd FragmentTypeAndType | EventCollection URI template | 1 | Read-only collection of all events from a particular type, containing a particular fragment type, from a particular period (placeholders {type}, {dateFrom}, {dateTo}, {fragmentType}). |
GET - Event API resource
Response body: application/vnd.com.nsn.cumulocity.inventoryApi+json
Required role: ROLE_EVENT_READ
Example request - Get the event API resource
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200 - OK
GET <<url>>/event
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.eventapi+json;ver=… |
HTTP/1.1
200 - OK
{
"self" : "<<Event API URL>>",
"events" : {
"self" :"<<EventCollection URL>>"
},
"eventsForType" : "<<EventCollection URL>>?type={type}",
"eventsForSource" : "<<EventCollection URL>>?source={source}",
"eventsForTime" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
"eventsForFragmentType" : "<<EventCollection URL>>?fragmentType={fragmentType}",
"eventsForSourceAndType" : "<<EventCollection URL>>?type={type}&source={source}",
"eventsForSourceAndTime" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
"eventsForSourceAndFragmentType" : "<<EventCollection URL>>?source={source}&fragmentType={fragmentType}",
"eventsForDateAndFragmentType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
"eventsForFragmentTypeAndType" : "<<EventCollection URL>>?fragmentType={fragmentType}&type={type}",
"eventsForTimeAndType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
"eventsForSourceAndDateAndFragmentType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
"eventsForSourceAndDateAndFragmentTypeAndType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}",
"eventsForSourceAndFragmentTypeAndType" : "<<EventCollection URL>>?source={source}&fragmentType={fragmentType}&type={type}",
"eventsForSourceAndTimeAndType" : "<<EventCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
"eventsForDateAndFragmentTypeAndType" : "<<EventCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}"
}
Event collection
EventCollection [application/vnd.com.nsn.cumulocity.eventCollection+json]
Name | Type | Occurs | Description |
---|---|---|---|
self | string | 1 | A URI linking to this resource. |
events | Event | 0..n | List of events, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | string | 0..1 | A URI linking to a potential previous page of events. |
next | string | 0..1 | A URI linking to a potential next page of events. |
GET - Event collection
Response body: application/vnd.com.nsn.cumulocity.eventcollection+json
Required role: ROLE_EVENT_READ
Example request - Retrieve information about an event collection
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
200-OK
GET <<url>>/event/events
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.eventcollection+json;ver=… |
HTTP/1.1
200 - OK
{
"self":"...",
"events":[
{
"id" : "10",
"self" : "...",
"creationTime" : "2011-09-06T12:03:27.927+02:00",
"type" : "com_cumulocity_model_DoorSensorEvent",
"time" : "2011-09-06T12:03:27.845+02:00",
"text" : "Door sensor was triggered.",
"com_othercompany_Extension" : { ... },
"source":{
"name": "...",
"self": "...",
"id":"12345"}
},
{
"id":"11",
...
}
],
"statistics" : {
"totalPages" : 2,
"pageSize" : 5,
"currentPage : 1
}
}
POST - Create a new event
Request body: application/vnd.com.nsn.cumulocity.event+json;ver=…
Response body: application/vnd.com.nsn.cumulocity.event+json
Required role: ROLE_EVENT_ADMIN or owner of source object
Example request - Create a new event
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/json |
Accept | application/vnd.com.nsn.cumulocity.event+json |
POST /event/events
Host: <URL>
{
"time" : "2011-09-06T12:03:27.845+02:00",
"type" : "com_cumulocity_model_DoorSensorEvent",
"text" : "Door sensor was triggered.",
"source": {
"id" : "12345"
}
}
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
201 - Created
{
"id" : "10",
"self" : "<<URL of new event>>",
"time" : "2011-09-06T12:03:27.845+02:00",
"creationTime" : "2011-09-06T12:03:27.927+02:00",
"type" : "com_cumulocity_model_DoorSensorEvent",
"text" : "Door sensor was triggered.",
"source" : {
"id":"12345",
"self": "...",
"name": "..."
}
}
For POST requests, the source parameter is required to have only an id
.
The id
and creationTime
of the new event are generated by the server and returned in the response to the POST operation.
In case of executing range queries on events API, like query by dateFrom and dateTo, the latest events are returned first. It is possible to change the order by adding query parameter “revert=true” to the request URL. In many use cases it is needed to get the oldest event sent from the device. This can be accomplished by passing “revert” param together with “dateFrom” and “dateTo” params to sort the outcome by date, e.g. pass dateFrom from a year ago, and dateTo from the feature.
PUT - Update an event
Request body: application/vnd.com.nsn.cumulocity.event+json
Response body: application/vnd.com.nsn.cumulocity.event+json
Required role: ROLE_EVENT_ADMIN or owner of source object
Example Request - Change the text of an event
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | application/json |
Accept | application/vnd.com.nsn.cumulocity.event+json;ver=… |
PUT <<url>>/event/events/<<eventId>>
{
"text": "Life full of events"
}
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
200 - OK
{
"creationTime": "2016-11-08T16:07:40.917+01:00",
"time": "2014-03-03T12:03:27.845Z",
"id": "10",
"self": ".../event/events/<<eventId>>",
"source": {
"id": "12345",
"self": ".../inventory/managedObjects/<<objectId>>"
},
"text": "Life full of events",
"type": "TestAlarm"
}
DELETE - Delete an event collection
The DELETE method allows for deletion of event collections. Applicable query parameters are equivalent to GET method.
Request body: N/A
Response body: N/A
Required role: ROLE_EVENT_ADMIN
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
DELETE: <<url>>/event/events....
Example response
HTTP/1.1
204 - NO CONTENT
Info: DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted event has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested event is deleted after all associated data has been deleted.
Event
Event [application/vnd.com.nsn.cumulocity.event+json]
Name | Type | Occurs | Description | PUT/POST |
---|---|---|---|---|
id | string | 1 | Uniquely identifies an event. | No |
self | string | 1 | A URI linking to this resource. | No |
creationTime | datetime | 1 | Time when event was created in the database. | No |
type | string | 1 | Identifies the type of this event. | POST: Mandatory PUT: No |
time | string | 1 | Time of the event. | POST: Mandatory PUT: No |
text | string | 1 | Text description of the event. | POST: Mandatory PUT: Optional |
source | ManagedObject | 1 | The ManagedObject that the event originated from, as object containing properties “id”, “self”, “name”, and “type”. | POST: Mandatory PUT: No |
* | Object | 0..n | Additional properties of the event. | POST: Optional PUT: Optional |
GET - Representation of an event
Response body: application/vnd.com.nsn.cumulocity.event+json
Required role: ROLE_EVENT_READ
Example request - Retrieve information about an event
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
GET <<url>>/event/events/<<eventID>>
Example response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
200 OK
{
"id" : "10",
"self" : "...",
"time" : "2011-09-06T12:03:27.845+02:00",
"creationTime" : "2011-09-06T12:03:27.927+02:00",
"type" : "com_cumulocity_model_DoorSensorEvent",
"text" : "Door sensor was triggered.",
"source" : {
"id":"12345",
"self ": "..."
}
}
DELETE - Delete an event
Request Body: N/A.
Response Message Body: N/A.
Required role: ROLE_EVENT_ADMIN or owner of source object.
Example Request - Delete an event
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
DELETE <<url>>/event/events/<<eventID>>
Example Response
HTTP/1.1
204 NO CONTENT
Info: DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted event has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested event is deleted after all associated data has been deleted.
Notifications
With the event notification API it is possible to receive updates for all events for a specific device. The basic protocol for receiving notifications is described in the Section “Real-time notifications”. The URL is
/cep/realtime
The subscription channel needs to contain the managed object ID of the device or a “*” as placeholder to receive notifications for the events of all devices
/events/<<deviceId>>
The response will additionally to the event object contain a “realtimeAction” to identify which action resulted in the given object (CREATE, UPDATE or DELETE). In case of a deletion the data will only contain the ID of the deleted event.
Required role: ROLE_EVENT_READ
Example Response:
HEADERS | |
---|---|
Content-Type | application/json |
HTTP/1.1
200 - OK
[
{
"channel": "/events/12345",
"successful": true,
"error": "",
"data": [{
"realtimeAction": "CREATE",
"data": {
"id": "1",
"self": "...",
"source": {
"12345"
},
"creationTime": "2011-09-06T12:03:27.927+02:00",
"text": "event has been triggered"
}
}],
"clientId": "Un1q31d3nt1f13r"
}
]
Binaries
The events Rest API has the possibility to store/retrieve and delete binaries for events.
Every event can have one binary attached.
GET - Download a binary
Required role: ROLE_EVENT_READ
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
GET <<url>>/event/events/<<eventId>>/binaries
Example response
Response when binary exists:
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
Content-Disposition | attachment; filename=”file.txt” |
HTTP/1.1
200 OK
<<content-body>>
Response when binary doesn’t exists or is only partially uploaded or when event doesn’t exist:
HTTP/1.1
404 OK
<<error-message>>
POST - Upload a binary
Using POST method it is possible to upload binary file as attachment to Event. Size of attachment cannot exceed 50MB.
Required role: ROLE_EVENT_ADMIN
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
POST <<url>>/event/events/<<eventId>>/binaries
Example response
Successful response:
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
201 Created
{
"self”: “<<url>>/event/events/<<eventId>>/binaries”,
“type”: “<<content-type>>”,
“source”: <<eventId>>,
“length”: <<content-lenght>>
}
Response when event doesn’t exist:
HTTP/1.1
404 NOT FOUND
<<error-message>>
Response when binary already exists:
HTTP/1.1
409 CONFLICT
<<error-message>>
Corresponding event will have fragment:
{
...
“c8y_IsBinary”: {
“type”: “<<content-type>>”
}
...
}
POST multipart/form-data - Upload a binary
Uploading functionality is also available using multipart request.
Required role: ROLE_EVENT_ADMIN
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Type | multipart/form-data; boundary=–myBoundary |
POST <<url>>/event/events/<<eventId>>/binaries
--myBoundary
Content-Type: application/octet-stream
Content-Disposition: form-data; name="file.txt"
<<content-body>>
--myBoundary--
Successful response:
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
201 Created
{
"self”: “<<url>>/event/events/<<eventId>>/binaries”,
“type”: “application/octet-stream”,
“name”: “file.txt”,
“source”: <<eventId>>,
"length": <<lenght>>
}
POST content-range - Upload a binary
Files can be uploaded in many chunks using “Content-Range” header.
“Content-Range” header is in format “start-stop/length” where:
- “start” represents beginning of uploaded file, starting from 0,
- “stop” is end of file inclusive,
- “length” is length of whole document, the property is mandatory only in last chunk of file, in other cases it can be replaced with ‘*’
Ie having document with size 10 we can create chunks: “0-3/*”, “4-5/*”, “6-9/10”.
Size of single chunk cannot exceed 5MB.
Required role: ROLE_EVENT_ADMIN
Example first chunk request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Length | 100 |
Content-Range | 0-399/* |
POST <<url>>/event/events/<<eventId>>/binaries
<<content-body>>
Example response for first chunk
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
200 OK
{
"self”: “<<url>>/event/events/<<eventId>>/binaries”,
“type”: “<<content-type>>”,
“range”: “0-399/*”,
“source”: <<eventId>>
}
Corresponding event will have fragment:
{
...
“c8y_IsIncompleteBinary”: {
“range”: “0-399/*”
}
...
}
Example last request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
Content-Length | 100 |
Content-Range | 400-499/500 |
POST <<url>>/event/events/<<eventId>>/binaries
Example response for last chunk
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
201 Created
{
"self”: “<<url>>/event/events/<<eventId>>/binaries”,
“type”: “<<content-type>>”,
“source”: <<eventId>>,
“length”: <<content-lenght>>
}
PUT - Replace existing binary
Required role: ROLE_EVENT_ADMIN
Example request
HEADERS | |
---|---|
Authorization | {{auth}} |
Host | {{hostname}} |
PUT <<url>>/event/events/<<eventId>>/binaries
<<content-body>>
Successful response
HEADERS | |
---|---|
Content-Type | application/vnd.com.nsn.cumulocity.event+json;ver=… |
HTTP/1.1
201 Created
{
"self”: “<<url>>/event/events/<<eventId>>/binaries”,
“type”: “<<content-type>>”,
“source”: <<eventId>>,
“length”: <<content-lenght>>
}
DELETE - Delete a binary
Required role: ROLE_EVENT_ADMIN
Example request
DELETE <<url>>/event/events/<<eventId>>/binaries
Authorization: Basic <<auth>>
Example response
Request Body: N/A.
Response Message Body: N/A.
Example response when binary exists:
HTTP/1.1
204 NO CONTENT
Example response when binary or event doesn’t exist:
HTTP/1.1
404 NOT FOUND
<<error-message>>