Applications REST Interface
Data
An application data structure contains at least the following fields:
-
name
The name of the application as it’s shown in the user interface.
-
uuid
The application UUID.
-
capability
The application’s capability.
-
default_charset
The default charset of the application.
-
logonly_ruleset_version
The UUID of the detection ruleset.
-
active_ruleset_version
The UUID of the protection ruleset.
-
protected
True/false value telling whether the application is in protection mode.
-
bypass_ruleset
True/false value telling whether the ruleset is deactivated.
-
block_traffic
True/false value telling whether all traffic is blocked.
-
active_ruleset_baseline_config_version
The baseline version used for the application.
Getting a list of applications
-
Request
Method GET URL
/applications/
Arguments
–
-
Response
Return code Arguments Meaning 200
{ UUID1: {APPINFO1}, UUID2: {APPINFO2}
the list of applications was successfully returned as a dictionary mapping the application UUIDs to some of their metadata.
401
-
no login
403
-
not enough rights
500
-
internal server error
-
Example
The following request retrieves a list of all applications. Note that these applications are listed by their UUIDs, not by their names.
$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/applications { "__name": "applications", "__path": "/api/af/2.0/applications/", "__subnodes": [ "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c", "f011694d47d73578-e440fd26a125de02c57dc7efa1f1bc17" ], "applications": { "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c": { "block_traffic": false, "last_modified": 0, "name": "wiki", "protected": false }, "f011694d47d73578-e440fd26a125de02c57dc7efa1f1bc17": { "block_traffic": false, "last_modified": 0, "name": "website", "protected": false } } }
Getting the data of an application
-
Request
Method GET URL
/applications/UUID
Arguments
–
-
Response
Return code Arguments Meaning 200
{ APPDATA }
dictionary containing detailed application data successfully returned
401
-
no login
403
-
not enough rights
404
-
application UUID doesn't exist
500
-
internal server error
-
Example
The following request retrieves the data of the application "wiki". Note that you don't use the application name in the request, but the UUID.
$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/applications/f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c { "__name": "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c", "__path": "/api/af/2.0/applications/f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c/", "__subnodes": [ "rulesets" ], "active_ruleset_baseline_config_version": "", "active_ruleset_version": "127.0.0.1:8083:f011694d47d73578-1a7bfe29b480dac5575de4bc15d85a6f:1", "block_traffic": false, "bypass_ruleset": false, "capability": "none", "default_charset": "UTF-8", "error_id_config": { "mode": "standard", "html_template": "\n<html>\n<head>\n <style type=\"text/css\">\n p {margin-left:20px;}\n a {color: #fff;}\n body {background: #ffffff;}\n div#middle {\n position:absolute;\n left:50%;\n top:50%;\n height:300px;\n width:600px;\n margin-top:-250px;\n margin-left:-308px;\n background-color: #dd682a;\n vertical-align: middle;\n overflow:hidden;\n text-align:center;\n }\n .round-corners { -moz-border-radius: 5px; -webkit-border-radius: 5px; border-radius: 5px; }\n .shadow { -moz-box-shadow: 5px 5px 5px #aaa; -webkit-box-shadow: 5px 5px 5px #aaa; box-shadow: 5px 5px 5px #aaa; }\n\n #one, #two {\n width: 45%;\n height: 10%;\n }\n\n #left, #right {\n width: 45%;\n height: 300%;\n margin-left:auto;\n martin-top: 100px;\n padding: 10px;\n }\n #left { float:left; font-size: 100px; color: #fff; top: 50px;}\n #right { float:right;color: #fff; top: 50px;}\n </style>\n <title>An error occurred. {{ERROR-CODE}}</title>\n</head>\n<body>\n<div id=\"middle\" class=\"round-corners shadow\">\n <div id=\"one\"></div>\n <div id=\"two\"></div>\n <div id=\"left\">{{ERROR-CODE}}</div>\n <div id=\"right\">If you'd like to report this error back to us, please include the following error ID in a email to:<br /><br />[email protected]<br /><br />{{ERROR-ID}}</div>\n<br style=\"clear:both;\"/>\n</div>\n</body>\n</html>\n", "url_template": "http://localhost/errorpage?code={{ERROR-CODE}}&id={{ERROR-ID}}" }, "last_modified": 0, "logonly_ruleset_version": "127.0.0.1:8083:f011694d47d73578-1a7bfe29b480dac5575de4bc15d85a6f:1", "name": "wiki", "protected": false, "reduced_logging_hosts": [], "reduced_url_logging": false, "uuid": "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c" }
Adding an application
-
Request
Method POST URL
/applications/
Arguments
{ 'name': applicationname, ... }
When adding an application, the name is required. However, you can’t specify the following fields:
uuid logonly_ruleset_version active_ruleset_version
-
Response
Reason code Arguments Meaning 200
{ 'uuid': UUID }
application with the given UUID successfully created; all application data is returned
401
-
no login
403
-
not enough rights
409
-
malformed, conflicting, or missing data or application already exists (names must be unique)
500
-
internal server error
-
Example
The following request adds an application named "wiki". All fields that aren't specified (all except name and hosts in this case) automatically get some default values. The name of the application is a UUID, which is used as an internal key. In contrast to this, the name is shown in the user interface.
$ curl -u admin:admin -H 'Content-Type: application/json' --data '{"name":"wiki", "hosts":["10.1.0.42"]}' http://127.0.0.1:8087/api/af/2.0/applications { "__name": "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c", "__path": "/api/af/2.0/applications/f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c/", "__subnodes": [ "rulesets" ], "active_ruleset_baseline_config_version": "", "active_ruleset_version": "127.0.0.1:8083:f011694d47d73578-1a7bfe29b480dac5575de4bc15d85a6f:1", "block_traffic": false, "bypass_ruleset": false, "capability": "none", "customer_key": "", "default_charset": "UTF-8", "error_id_config": { "mode": "standard", "html_template": "\n<html>\n ... \n</html>\n", "url_template": "http://localhost/errorpage?code={{ERROR-CODE}}&id={{ERROR-ID}}" }, "hosts": [ "10.1.0.42" ], "last_modified": 0, "logonly_ruleset_version": "127.0.0.1:8083:f011694d47d73578-1a7bfe29b480dac5575de4bc15d85a6f:1", "name": "wiki", "protected": false, "reduced_logging_hosts": [], "reduced_url_logging": false, "uuid": "f011694d47d73578-3c0581461472821ff8d0c3a8c007d88c" }
Changing an application
-
Request
Method PUT URL
/applications/UUID
Arguments
{ APPDATA }
When changing an application, you can’t specify the field uuid.
If you want to remove a host, you need to remove it both from the hosts list and from the reduced_logging_hosts list.
-
Response
Return code Arguments Meaning 200
-
application successfully changed
401
-
no login
403
-
not enough rights
404
-
application not found
409
-
malformed, conflicting, or missing data
500
-
internal server error
Deleting an application
-
Request
Method DELETE URL
/applications/UUID
Arguments
–
-
Response
Reason code Arguments Meaning 200
-
application successfully deleted
401
-
no login
403
-
not enough rights
404
-
application not found
500
-
internal server error