We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Complex Event Processing Open RESTful API Specification - FIWARE Forge Wiki

Complex Event Processing Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the CEP GE REST API

As described in the CEP GE open specification document FIWARE.ArchitectureDescription.Data.CEP, CEP has three main interfaces: one for receiving raw events from event producers using a RESTful service, second for sending output events to event consumers using an output REST client adapter, and a third for administrating the CEP engine state, and its definition repository. Following are detailed descriptions and examples of the APIs since the 2nd release of the CEP GE.

Please check the Legal Notice to understand the rights to use FI-WARE Open Specifications.

The CEP APIs

The CEP supports RESTful, resource-oriented APIs accessed via HTTP for:

  1. Receiving events in JSON-based, tag-delimited or XML-NGSI format via a provided service using POST
  2. Sending events in JSON-based, tag-delimited or XML-NGSI format via a REST client using POST
  3. Administrating CEP via a provided service for:
    1. Managing the definitions repository (adding, replacing and deleting definitions)
    2. Managing engine instances (changing their definitions and start\stop the instances)

Intended Audience

This specification is intended for software developers that want to use the CEP GE allowing it to get incoming events and send output events. To use this information, the reader should have a general understanding of the Generic Enabler service FIWARE.ArchitectureDescription.Data.CEP. You should also be familiar with:

  • ReSTful web services
  • HTTP/1.1
  • JSON, tag-delimited, or XML/NGSI data serialization formats

API Change History

This version of the CEP API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 30, 2012
  • Initial Version
Apr 30, 2013
  • 2nd Release Version
Apr 30, 2014
  • 3rd Release Version

How to Read This Document

The assumption is that a reader is familiarized with REST architecture style. For descriptions of terms used in this document see FIWARE.ArchitectureDescription.Data.CEP.

Additional Resources

For more details on the CEP GE Adapters and Architectural Description of the CEP GE please refer to FIWARE.ArchitectureDescription.Data.CEP.

General CEP API Information

Resources Summary

  • The CEP GE provides a REST service allowing for external systems to push events using the POST method.

http://{server}:{port}/{instance_name}/rest/events

  • The CEP GE uses a REST output adapter which is a client that activates a REST service using the POST method.
  • The CEP GE provides a REST service for administrating the generic enabler. It allows for managing the definitions repository

http://{server}:{port}/{CEP_Admin}/resources/definitions/{definition_name} and the engine instances http://{server}:{port}/{CEP_Admin}/resources/instances/{instance_name}

Representation Format

For incoming and outgoing events, CEP GE supports JSON-based, tag-delimited or XML-NGSI format.

The receiving event service will accept either formats automatically, when the content-type is provided. Use application/json Content-Type for JSON events, text/plain Content-Type for tag-delimited events and application/xml Content-Type for XML-NGSI events.

The client for notifying on events using the REST output adapter is configured with one of the formats when defining the consumer in the Event Processing Network (using the authoring tool). This will define the Content-Type header of the request to be issued.

Representation Transport

Resource representation is transmitted between client and server by using the HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of the wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.


API Operations

In this section we describe each operation in-depth for each provided resource.

Receiving Events API

The CEP GE provides a REST service for receiving events. (Pulling events from an externally provided REST service, as was supported in Release 1, still exists as an input adapter and details for using this adapter are within the programmer guide)

Verb URI example Description
POST /{instance_name}/rest/events Receive events by the specified engine instance

Usage Examples

In tag-delimited format:

POST //localhost:8080/ProtonOnWebServer/rest/events
Content-Type: text/plain 
Name=TrafficReport;volume=1000;

In JSON format:

POST //localhost:8080/ProtonOnWebServer/rest/events 
Content-Type: application/json
{"Name":"TrafficReport", "volume":"1000"}

In XML/NGSI format:

POST //localhost:8080/ProtonOnWebServer/rest/events 
Content-Type: application/xml
<notifyContextRequest>
  <subscriptionId>51a60c7a286043f73ce9606c</subscriptionId>
  <originator>localhost</originator>
  <contextResponseList>
    <contextElementResponse>
      <contextElement>
        <entityId type="Node" isPattern="false">
          <id>OUTSMART.NODE_3505</id>
        </entityId>
        <contextAttributeList>
          <contextAttribute>
            <name>TimeInstant</name>
            <type>urn:x-ogc:def:trs:IDAS:1.0:ISO8601</type>
            <contextValue>2013-05-31T18:59:08+0300</contextValue>
          </contextAttribute>
          <contextAttribute>
            <name>presence</name>
            <type>urn:x-ogc:def:phenomenon:IDAS:1.0:presence</type>
            <contextValue></contextValue>
          </contextAttribute>
          <contextAttribute>
            <name>batteryCharge</name>
            <type>urn:x-ogc:def:phenomenon:IDAS:1.0:batteryCharge</type>
            <contextValue>2</contextValue>
          </contextAttribute>
          <contextAttribute>
            <name>illuminance</name>
            <type>urn:x-ogc:def:phenomenon:IDAS:1.0:illuminance</type>
            <contextValue></contextValue>
          </contextAttribute>
          <contextAttribute>
            <name>Latitud</name>
            <type>urn:x-ogc:def:phenomenon:IDAS:1.0:latitude</type>
            <contextValue></contextValue>
          </contextAttribute>
          <contextAttribute>
            <name>Longitud</name>
            <type>urn:x-ogc:def:phenomenon:IDAS:1.0:longitude</type>
            <contextValue></contextValue>
          </contextAttribute>
        </contextAttributeList>
      </contextElement>
      <statusCode>
        <code>200</code>
        <reasonPhrase>OK</reasonPhrase>
      </statusCode>
    </contextElementResponse>
  </contextResponseList>
</notifyContextRequest>

Note:

Name is a built-in attribute used to represent the event type being reported. Please consult the user guide for event representation and built-in attributes.

The data in the tag format should be given with no blanks.

In the JSON format, all the attributes values are given as strings, the CEP processes each attribute value according to its defined type (in the event definition).

Sending Events API

The CEP GE activates a REST client for sending output events (in a push mode).

Verb URI example Description
POST /application-name/consumer Send a derived event to a consumer

Usage Examples

The following is what the REST output adapter will generate as a request to a REST service called /application-name/consumer and is expected to be able to interpret either the tag-delimited, JSON or XML/NGSI format via the POST method.

Note: ’’’Name’’’ is a built-in attribute used to represent the event type being reported. Please consult the user guide for event representation and built-in attributes.

In tag-delimited format:

POST //localhost:8080/application-name/consumer 
Content-type: text/plain
Name=TrafficReport;Certainty=0.0;Cost=0.0;EventSource=;OccurrenceTime=null;Annotation=;Duration=0.0;volume=1000;
EventId=40f68052-3c7c-4245-ae5a-6e20def2e618;ExpirationTime=null;Chronon=null;DetectionTime=1349181899221;

In JSON format:

POST //localhost:8080/application-name/consumer 
Content-type: application/json
{"Cost":"0.0","Certainty":"0.0","Name":"TrafficReport","EventSource":"","Duration":"0.0","Annotation":"",
 "volume":"1000","EventId":"e206b5e8-9f3a-4711-9f46-d0e9431fe215","DetectionTime":"1350311378034"}

In XML/NGSI format:

POST //localhost:8080/application-name/consumer 
Content-type: application/xml
<updateContextRequest>
   <contextElementList>
    <contextElement>
                 <entityId type="CEPEventReporter" isPattern="false">
                        <id>CEPEventReporter_Singleton</id>
                 </entityId>
                <contextAttributeList>
           <contextAttribute>
            <name>EventId</name>
                  <contextValue>4be0ab1c-ec30-4525-b278-78222f3ce081</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>EventType</name>
                  <contextValue>LowBatteryAlert</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>DetectionTime</name>
                  <contextValue>2013-06-05T08:25:15.804000CEST</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>EventSeverity</name>
                  <contextValue>Critical</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>Cost</name>
                  <contextValue>0.0</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>Certainty</name>
                  <contextValue>1</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>Name</name>
                  <contextValue>LowBatteryAlert</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>OccurrenceTime</name>
                  <contextValue>2013-06-05T08:25:15.804000CEST</contextValue>
         </contextAttribute>
         <contextAttribute>
            <name>TimeInstant</name>
                  <contextValue>2013-06-05T08:24:45.581000CEST</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>Duration</name>
                  <contextValue>0</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>AffectedEntityType</name>
                  <contextValue>Node</contextValue>
         </contextAttribute>
           <contextAttribute>
            <name>AffectedEntity</name>
                  <contextValue>OUTSMART.NODE_3505</contextValue>
         </contextAttribute>
      </contextAttributeList>
    </contextElement>
   </contextElementList>
   <updateAction>UPDATE</updateAction>
</updateContextRequest> 

Managing the Definitions Repository

The CEP GE provides a REST service for managing the definitions repository. The repository is a file directory. Adding or deleting a definition will add or remove a file from the directory respectively. Each definition is identified via a unique name (prefixed by the repository location) and a URI associated with it. The URI is used to retrieve the file by the applications that make use of the definition.

Verb URI example Description
GET /{CEP_Admin}/resources/definitions Retrieve all the existing definitions in the repository
POST /{CEP_Admin}/resources/definitions Add a new definition
GET /{CEP_Admin}/resources/definitions/{definition_name} Retrieve the complete definition in JSON format
PUT /{CEP_Admin}/resources/definitions/{definition_name} Replace content of an existing definition with new content
DELETE /{CEP_Admin}/resources/definitions/{definition_name} Remove the definition from the repository

Usage Examples

  • Retrieving all definitions
GET //localhost:8080/ProtonOnWebServerAdmin/resources/definitions

Sample result:

[{"name":"D:\\Apps\\DoSAttack.json","url":"\/ProtonOnWebServerAdmin\/resources\/definitions\/DoSAttack"}]
  • Creating a new definition (notice the “name” property (containing the name for the definition) added alongside the “epn” property (containing the full definition)

The definition file itself, in JSON format, can be generated by the UI, and can be generated programmatically by any other application. The format of this definition file is described by a JSON schema for a CEP application while the semantics of the various elements in this schema are described in a user guide. Examples for definitions can be found in the CEP test plan

POST //localhost:8080/ProtonOnWebServerAdmin/resources/definitions
{"name":"MyDefinition","epn":{…}}

Result:

/ProtonOnWebServerAdmin/resources/definitions/MyDefinition


Performing GET on the returned resource will retrieve the complete definition (epn) in JSON format.

Administrating Instances

There are two administration actions that can be performed on an instance.

  1. Changing the definition (epn) for the instance to work with. This will define the types of events the instance will accept for processing and the type of patterns it will be computing.
  2. Starting or stopping the instance
Verb URI example Description
GET /{CEP_Admin}/resources/instances/{instance_name} Retrieve the status of an instance, the definition URI it is configured with and its state (stopped or started)
PUT /{CEP_Admin}/resources/instances/{instance_name} Configuring the instance with a definition file or start\stop the instance

Usage Examples

Retrieving an instance status

GET //localhost:8080/ProtonOnWebServerAdmin/resources/instances/ProtonOnWebServer

Sample result:

{"state":"started","definitions-url":"\/ProtonOnWebServerAdmin\/resources\/definitions\/DoSAttack"}


Configuring\changing a definition for an instance

PUT //localhost:8080/ProtonOnWebServerAdmin/resources/instances/ProtonOnWebServer
{"action":"ChangeDefinitions","definitions-url":"\/ProtonOnWebServerAdmin\/resources\/definitions\/DoSAttack"}

Starting an instance (replace start with stop to stop an instance)

PUT //localhost:8080/ProtonOnWebServerAdmin/resources/instances/ProtonOnWebServer
{"action":"ChangeState","state":"start"}
Personal tools
Create a book