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: , UUID2: | 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 |