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]
Name | Type | Occurs | Description |
---|---|---|---|
self | URL | 1 | Link to this resource. |
modules | ModuleCollection | 1 | Collection of all modules. |
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]
Name | Type | Occurs | Description |
---|---|---|---|
self | URI | 1 | Link to this resource. |
modules | Collection | 0..n | List of modules, see below. |
statistics | PagingStatistics | 1 | Information about paging statistics. |
prev | URI | 0..1 | Link to a potential previous page of modules. |
next | URI | 0..1 | Link to a potential next page of modules. |
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]
Name | Type | Occurs | Description | PUT/POST |
---|---|---|---|---|
id | String | 1 | Uniquely identifies a module. | No |
self | URI | 1 | Link to this resource. | No |
lastModified | String | 1 | Time when module was created or modified. | No |
name | String | 1 | The module name. | POST: Mandatory PUT: Optional |
status | String | 1 | The module status: DEPLOYED, NOT_DEPLOYED (default). | POST: No PUT: Optional |
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 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