API reference: Real-time statements

Overview

The API below is not yet published in “/platform” but can be reached using the URL “/cep”.

The real-time statements interface consists of five parts:

• The cep API resource returns a URI to a module collection.
• The module collection resource retrieves modules and enables creating new modules.
• The module resource represents an individual module that can be queried, modified, deployed or undeployed. 

Note that for all PUT/POST requests accept header should be provided, otherwise an empty response body will be returned.

Module API

CepApi [application/vnd.com.nsn.cumulocity.cepApi+json]

GET the CepApi resource

Response body: CepApi

Required role: ROLE_CEP_MANAGEMENT_READ

Example request: Retrieve the CepApi resource collection

GET /cep
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepapi+json;ver=...
Content-Length: ...
{
   "self":"<<CepAPI URL>>",
   "modules":{
      "self":"<<ModuleCollection URL>>"
   }
}

Module collection

ModuleCollection  [application/vnd.com.nsn.cumulocity.cepModuleCollection+json]

GET a module collection

Response body: ModuleCollection

Required role: ROLE_CEP_MANAGEMENT_READ

Example request: Get collection of all modules

GET /cep/modules
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepmodulecollection+json;ver=...
Content-Length: ...
{
   "id":"1",
   "self":"CURRENT URL",
   "name":"CepModule 1",
   "application":{
      "application":{
         "id":"3",
         "key":null,
         "name":"energyapp",
         "self":"<<this module application URL>>"
      },
      "self":"<<this module application reference URL>>"
   },
   "lastModified":"2012-01-10T17:15:24+01:00",
   "self": "<<URL to this module>>"
}

POST - Create a new Module with statements

Request body: module file Response body: Module (if “Accept” header is provided)
Required role: ROLE_CEP_MANAGEMENT_ADMIN.

Example request:

POST /cep/modules
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: multipart/form-data

Note: “POST /cep/modules” is a multipart message.

Example file:

module testmodule;
@Name('test1')select * from EventCreated.win:time(1 hour)

Annotation @Name can be skipped - in this case cumulocity platform will assign default name to the statement.

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.cepmodule+json;ver=...
{
   "id":"3",
   "lastModified":"2013-06-27T15:37:51.091+02:00",
   "name":"management",
   "self":"http:\/\/localhost:8181\/cep\/modules\/3",
   "status":"DEPLOYED"
}

The “id” and “lastModified” of the new module are generated by the server. Response contains also status of module deployment operation.

Module name is considered to be also application name.

Module

Module [application/vnd.com.nsn.cumulocity.cepModule+json]

GET Module

Response body: Module

Required role: ROLE_CEP_MANAGEMENT_READ

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepmodule+json;ver=...
Content-Length: ...
{
   "id":"1",
   "lastModified":"2013-04-08T14:35:29.879+02:00",
   "name":"the_module",
   "self":"<<URL of cepModule>>",
   "status":"NOT_DEPLOYED"
}

GET Module file with statements

Response body: text/plain

Required role: ROLE_CEP_MANAGEMENT_READ

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: ...

@Name('test1')select * from EventCreated.win:time(1 hour)@Name('test2')select id, count(*) from MyOffOnStream.win:time(1 hour) group by id;

Warning: if given statement has default name assigned by cumulocity platform, annotation @Name will not appear.

Update Module

Request body: Module

Response body: Module (only if “Accept” header is provided)

Required : ROLE_CEP_MANAGEMENT_ADMIN

Example Request:

PUT /cep/modules/<<moduleId>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.cepmodule+json;ver=...
{
  "name" : "the_module",
  "status" : "DEPLOYED"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepmodule+json;ver=...

Update module file - Modify a Module with statements

Request body: module file Response body: Module (if “Accept” header is provided)
Required role: ROLE_CEP_MANAGEMENT_ADMIN.

Example request:

PUT /cep/modules/<<moduleId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: text/plain

Example file:

module testmodule;
@Name('test1')select * from EventCreated.win:time(1 hour)@Name('test2')select id, count(*) from MyOffOnStream.win:time(1 hour) group by id;

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.cepmodule+json;ver=...
{
   "id":"3",
   "lastModified":"2013-06-27T15:37:51.091+02:00",
   "name":"management",
   "self":"http:\/\/localhost:8181\/cep\/modules\/3",
   "status":"DEPLOYED"
}

During module modification old module is deleted and undeployed and new module is created and deployed, therefore module id changes.

DELETE a module

Request Body: N/A. Required : ROLE_CEP_MANAGEMENT_ADMIN

Example Request: Delete a module

DELETE /cep/modules/<<moduleId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example Response:

HTTP/1.1  204 NO CONTENT

Notifications

The real-time notifications allow for receiving almost immediately outputs from statements. They are available on URL "/cep/notifications", the usage is described in a separate document.

Required role: ROLE_NOTIFICATION_READ

The subscription channel name format

The subscription channel contains the name of the module in which the real-time statement is defined and the name of the real-time statement itself. It has the following structure:

/<<moduleName>>/<<statementName>>

For example, to subscribe on notifications from a statement “overHeatAlarms” in the module “alarms”, the subscription channel should be the following string:

/alarms/overHeatAlarms