Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 3.88 KB

api.md

File metadata and controls

89 lines (62 loc) · 3.88 KB

API

FIXME: A draft OpenAPI document for the API is available here, but it is not finished yet.

A description of "plain"" rules can be found at plain rules.

Visual Rules are intended to be used by the Portal exclusively, until a new format is developed which will replace the old format eventually. So, basically, the DCA's documentation is the reference.

Notices/notifications follow the format defined in Orion (Context Broker) for "notify" actions. Context subscriptions

All HTTP request must have application/json as MIME type. Responses are application/json also. Generally, the JSON returned as response includes a error field with a string describing an error or null if everything worked fine.

Every request should send a field header for the service (Fiware-Service) and the subservice (Fiware-ServicePath) it refers to.

For service and servicepath only alphanumeric and underscore characters are allowed.

The servicepath is a set of scopes separated by "/" and has the following limitations:

  • each scope must start with "/"
  • 10 maximum scope levels in a path
  • 50 maximum characters in each level, only alphanum and underscore allowed
  • Empty scopes are not allowed, at least it has to have length 1 (excluding the "/")

Fiware-ServicePath is an optional header. It is assumed that requests without Fiware-ServicePath belongs to a root scope "/" implicitely.

Internally to the CEP, scopes do not have a special meaning, so the entire servicepath string is used as a unit, and no operation of CEP takes into account a particular scope inside servicepath. Note this is the current behaviour, although it could change in the future to align more closely to how Orion uses service path (i.e. in a hierarchical way)

Notifications

Method Path Description
POST /notices Send an event/notification to perseo

Rules

CRUD for "plain" rules

Method Path Description
GET /rules List all rules
GET /rules/{id} Get rule with nameID
POST /rules Add rule
DELETE /rules/{id} Delete rule with nameID
PUT /rules/{id} Update a rule with name ID

Visual Rules

CRUD for Visual Rules. Originally detailed in DCA documentation (RESTAPI-SBC_2.6, section 6.15).

Method Path
GET /m2m/vrules
GET /m2m/vrules/{id}
POST /m2m/vrules
DELETE /m2m/vrules/{id}
PUT /m2m/vrules/{id}

Version

Method Path Description
GET /version Get version of perseo

Log level

Method Path Description
PUT /admin/log?level={level} Set log level of perseo
GET /admin/log Get the current log level of perseo

Pagination

Perseo-fe implements a pagination mechanism in order to help clients to retrieve large sets of resources. This mechanism works for all listing operations in the API (GET /rules, GET /vrules)

The mechanism is based on three URI parameters:

  • limit: in order to specify the maximum number of elements (default is 20, maximum allowed is 1000).
  • offset: in order to skip a given number of elements at the beginning (default is 0)
  • count (as option): if activated then a Fiware-Total-Count header is added to the response, with a count of total elements.