Management interface
Content:
- Apiary version of this document
- GET
/v1/version
- GET
/v1/stats
- PUT
/v1/stats
- GET
/v1/groupingrules
- POST
/v1/groupingrules
- PUT
/v1/groupingrules
- DELETE
/v1/groupingrules
- GET
/admin/log
- PUT
/admin/log
- POST
/v1/subscriptions
NGSI Version 1
NGSI Version 2
- DELETE
/v1/subscriptions
- GET
/v1/subscriptions
Apiary version of this document
This API specification can be checked at Apiary as well.
GET /v1/version
Gets the version of the running software, including the last Git commit:
GET http://<cygnus_host>:<management_port>/v1/version
Response:
{
"success": "true",
"version": "0.12.0_SNAPSHOT.52399574ea8503aa8038ad14850380d77529b550"
}
GET /v1/stats
Gets statistics about the configured Flume components. It is important to note in order to gathering statistics from the channels, these must be of type com.telefonica.iot.cygnus.channels.CygnusMemoryChannel
or com.telefonica.iot.cygnus.channels.CygnusFileChannel
.
Regarding the sources, it returns:
- Name of the source as written in the configuration.
- Setup time of the source.
- Status of the source, i.e. started or stopped.
- Number of processed events, i.e. number of events received by the source and attempeted to be put in the channels.
- Number of finally events put in the channels.
Regarding the channels, it returns:
- Name of the channel as written in the configuration.
- Setup time of the channel.
- Status of the channel, i.e. started or stopped.
- Number of events currently at the channel.
- Number of successful puts.
- Number of failed puts.
- Number of sucessful takes.
- Number of failed takes.
Regarding the sinks, it returns:
- Name of the sink as written in the configuration.
- Setup time of the sink.
- Status of the sink, i.e. started or stopped.
- Number of processed events, i.e. number of events taken from the channel and attempted for persistence.
- Number of finally persisted events.
GET http://<cygnus_host>:<management_port>/v1/stats
Response:
{
"stats": {
"channels": [
{
"name": "mysql-channel",
"num_events": 0,
"num_puts_failed": 0,
"num_puts_ok": 11858,
"num_takes_failed": 1,
"num_takes_ok": 11858,
"setup_time": "2016-02-05T10:34:25.80Z",
"status": "START"
}
],
"sinks": [
{
"name": "mysql-sink",
"num_persisted_events": 11800,
"num_processed_events": 11858,
"setup_time": "2016-02-05T10:34:24.978Z",
"status": "START"
}
],
"sources": [
{
"name": "http-source",
"num_processed_events": 11858,
"num_received_events": 11858,
"setup_time": "2016-02-05T10:34:24.921Z",
"status": "START"
}
]
},
"success": "true"
}
PUT /v1/stats
Resets the statistics about the configured Flume components. It is important to note in order to reset statistics from the channels, these must be of type com.telefonica.iot.cygnus.channels.CygnusMemoryChannel
or com.telefonica.iot.cygnus.channels.CygnusFileChannel
.
PUT http://<cygnus_host>:<management_port>/v1/stats
Response:
{"success":"true"}
GET /v1/groupingrules
Gets the configured grouping rules.
GET http://<cygnus_host>:<management_port>/v1/groupingrules
Response:
{
"grouping_rules": [
{
"destination": "allcars",
"fields": [
"entityType"
],
"fiware_service_path": "cars",
"id": 1,
"regex": "Car"
},
{
"destination": "allrooms",
"fields": [
"entityType"
],
"fiware_service_path": "rooms",
"id": 2,
"regex": "Room"
}
],
"success": "true"
}
POST /v1/groupingrules
Adds a new rule, passed as a Json in the payload, to the grouping rules.
POST http://<cygnus_host>:<management_port>/v1/groupingrules
{
"regex": "Room",
"destination": "allrooms",
"fiware_service_path": "rooms",
"fields": ["entityType"]
}
Response:
{"success":"true"}
Please observe the id
field is not passed as part of the posted Json. This is because the Management Interface automatically deals with the proper ID insertion.
PUT /v1/groupingrules
Updates an already existent grouping rules, given its ID as a query parameter and passed the rule as a Json in the payload.
PUT http://<cygnus_host>:<management_port>/v1/groupingrules=id=2
{
"regex": "Room",
"destination": "otherrooms",
"fiware_service_path": "rooms",
"fields": ["entityType"]
}
Response:
{"success":"true"}
DELETE /v1/groupingrules
Deletes a grouping rules, given its ID a a query parameter.
DELETE http://<cygnus_host>:<management_port>/v1/groupingrules?id=2
Response:
{"success":"true"}
GET /admin/log
Gets the log4j configuration (relevant parts, as the logging level or the appender names and layouts).
GET http://<cygnus_host>:<management_port>/admin/log
Responses:
200 OK
{
"log4j": {
"appenders": [
{
"layout": "...",
"name": "..."
}
],
"level": "..."
},
"success": "true"
}
500 Internal Server Error
{
"error": "..."
}
PUT /admin/log
Updates the logging level of Cygnus, given the logging level as a query parameter.
Valid logging levels are DEBUG
, INFO
, WARNING
(WARN
also works), ERROR
and FATAL
.
PUT http://<cygnus_host>:<management_port>/admin/log?level=<log_level>
Responses:
200 OK
400 Bad Request
{"error":"Invalid log level"}
400 Bad Request
{"error":"}
POST /v1/subscriptions
NGSI Version 1
Creates a new subscription to Orion given the version of NGSI (ngsi_version=1
in this case). The Json passed in the payload contains the Json subscription itself and Orion's endpoint details.
POST "http://<cygnus_host>:<management_port>/v1/subscriptions&ngsi_version=1"
{
"subscription":{
"entities": [
{
"type": "Room",
"isPattern": "false",
"id": "Room1"
}
],
"attributes": [],
"reference": "http://<reference_host>:<reference_port>",
"duration": "P1M",
"notifyConditions": [
{
"type": "ONCHANGE",
"condValues": []
}
],
"throttling": "PT5S"
},
"endpoint":{
"host":"<endpoint_host>",
"port":"<endpoint_port>",
"ssl":"false",
"xauthtoken":"234123123123123"
}
}
Responses:
Valid subscription:
{"success":"true","result" : {{"subscribeResponse":{"duration":"P1M","throttling":"PT5S","subscriptionId":"56f9081c3c6fb7e9d2a912a0"}}}}
Invalid subscription (Unknown fields in this case):
{"success":"true","result" :{"subscribeError":{"errorCode":{"code":"400","reasonPhrase":"Bad Request","details":"JSON Parse Error: unknown field: \/extraField"}}}
Invalid JSON (Empty field and missing field):
{"success":"false","error":"Invalid subscription, field 'duration' is empty"}
{"success":"false","error":"Invalid subscription, field 'notifyConditions' is missing"
Please observe Cygnus checks if the Json passed in the payload is valid (syntactically and semantically).
NGSI Version 2
Creates a new subscription to Orion given the version of NGSI (ngsi_version=2
in this case). The Json passed in the payload contains the Json subscription itself and Orion's endpoint details.
POST "http://<cygnus_host>:<management_port>/v1/subscriptions&ngsi_version=2"
{
"subscription":{
"description": "One subscription to rule them all",
"subject": {
"entities": [
{
"idPattern": ".*",
"type": "Room"
}
],
"condition": {
"attrs": [
"temperature"
],
"expression": {
"q": "temperature>40"
}
}
},
"notification": {
"http": {
"url": "http://localhost:1234"
},
"attrs": [
"temperature",
"humidity"
]
},
"expires": "2016-05-05T14:00:00.00Z",
"throttling": 5
},
"endpoint":{
"host":"<endpoint_host>",
"port":"<endpoint_port>",
"ssl":"false",
"xauthtoken":"QsENv67AJj7blC2qJ0YvfSc5hMWYrs"
}
}
Responses:
Valid subscription:
{"success":"true","result" : {"SubscriptionID" : "572ae23d20e1387832ed98d0"}}
Invalid subscription (Unknown fields in this case):
{"success":"false","error":"Parse error, malformed Json. Check it for errors."}
Invalid JSON (e.g. Missing fields or invalid endpoint):
{"success":"false","error":"Invalid subscription, field 'xxxxxx' is missing"}
{"success":"false","error":"Missing endpoint"}
Please observe Cygnus checks if the Json passed in the payload is valid (syntactically and semantically).
DELETE /v1/subscriptions
Deletes a subscription made to Orion given its ID and the NGSI version. The Json passed in the payload contains the Orion's endpoint details.
DELETE "http://<cygnus_host>:<management_port>/v1/subscriptions?subscription_id=<subscriptionId>&ngsi_version=<ngsiVersion>"
Responses:
Subscriptions deleted in v1 and v2:
{"success":"true","result" : {" Subscription deleted "}
Wrong parameter:
{"success":"false","error":"Parse error, wrong parameter (subscription_id). Check it for errors."}
{"success":"false","error":"Parse error, wrong parameter (ngsi_version). Check it for errors."}
Wrong subscription ID:
[NGSI v1]
{"success":"false","result" : {{"subscriptionId":"571872a9c0585c7451571be4","statusCode":{"code":"404","reasonPhrase":"No context element found","details":"subscriptionId: \/571872a9c0585c7451571be4\/"}}}
[NGSI v2]
{"success":"false","result" : {{"description":"The requested subscription has not been found. Check id","error":"NotFound"}}
Empty or missing authentication token:
{"success":"false","error":"Empty Auth-Token. Required for DELETE subscriptions"}
{"success":"false","error":"Missing Auth-Token. Required for DELETE subscriptions"}
Missing fields (empty or not given):
{"success":"false","error":"Missing endpoint"}
{"success":"false","error":"Invalid endpoint, field 'host' is missing"}
{"success":"false","error":"Invalid endpoint, field 'ssl is empty"}
GET /v1/subscriptions
Gets an existent subscription from Orion, given the ngsi version and the subscription id as a query parameter.
Valid ngsi versions are 1
and 2
(This method only works with ngsi_version=2
due to this method is not implemented in version 1
).
GET "http://<cygnus_host>:<management_port>/v1/subscriptions?ngsi_version=<ngsiVersion>&subscription_id=<subscriptionId>" -d '{"host":"<host>", "port":"<port>", "ssl":"false", "xauthtoken":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'
Responses:
Valid and current subscription id with the correct ngsi version:
{"success":"true","result" : {{"notification":{"lastNotification":"2015-07-28T22:24:33.00Z","timesSent":8122767998226748692,"callback":"http:\/\/xxx.xxx.xx.xxx:xxxx\/ngsi10\/notifyContext","attributes":[]},"expires":"2016-09-25T08:17:47.00Z","subject":{"condition":{"expression":{"q":"","geometry":"","coords":"","georel":""},"attributes":["TimeInstant"]},"entities":[{"id":"","type":"sevilla:fountain","idPattern":"patternId"}]},"id":"54325022q460a3873d30oe95","status":"active"}}
Valid but inexistent subscription id with the correct ngsi version:
{"success":"false","result" : {{"description":"","error":"subscriptionId does not correspond to an active subscription"}}
Invalid ngsi version:
{"success":"false","error":"Parse error, invalid parameter (ngsi_version): Must be 1 or 2. Check it for errors."}
Valid but not implemented ngsi version (sending ngsi_version=1
):
{"success":"false","error":"GET /v1/subscriptions not implemented."}
Missing or empty parameters:
{"success":"false","error":"Parse error, missing parameter (subscription_id). Check it for errors."}
{"success":"false","error":"Parse error, empty parameter (ngsi_version). Check it for errors."}