API Documentation

Alert Manager Enterprise uses custom endpoints to carry out data manipulation tasks.

info

The API Documentation will be updated soon for Release 2.1

General Information

The following description for the endpoints of AME will briefly document the endpoint name, the expected input, and the desired output. There is some vital information to consider when testing or developing new integration features for AME.

info

Every endpoint should reply with a 401 Forbidden or a 200 OK. The 200 OKdoes not always mean that the request was processed successfully. It only means that the endpoint replied and the session_key is valid. To debug endpoint behavior, it is necessary to have a look at the following logs datapunctum_ame_service.log for internal processing of the data and the datapunctum_ame_handler.log for the information about the endpoint handler script.

If, however, a request fails or due to wrong parameters, the reply will be 200 OK as well. Resulting in a response body like this:

failed_response

{
    "method": "POST",
    "error": null
}

The exception or action will be logged and can be viewed in the log files stated in the information box above. The behavior of the API does not fully comply with RESTful standards; there are no media types, no reference links, and the resources are just "plain old JSON”. XML is not supported, and it is not planned to be supported at any time. If you have to use XML, it is recommended to implement a translator pattern.

Command Pattern

Instead of posting entire resources for create, update, and delete actions, the frontend and backend are programmed to process commands that contain actions. For example, if you want to update an event, you send the following command:

update_event_command

{
    "action": "update",
    "updateObject": {
        "attribute": "<event-attribute>",
        "value": "<new-value>"
    },
    "event": {
        "_key": "<event-key>",
        "tenant_uid": "<event-tenant_uid>"
    },
    "comment": "reason for update"
}

The idea behind this is that if you want something to happen that concerns several different bits of information that have to be processed by the backend simultaneously, you only send one request. These Actions, as described in the following chapter about endpoints, are only available for POST endpoints since GET requests don’t send a body.

Endpoints

In this chapter, all requests are sent to a local Splunk host localhost listening on port 8089. If Splunk is configured to listen on a different endpoint, make sure to update the request.

/ame_events

https://localhost:8089/services/ame_events

Methods: GET, POST, [DELETE *]

Actions: insert, update, bulk-update, comment

[*] Please note that DELETE acts as a hard reset (drop all entries) for the alertqueue and the ame_default_events and can only be used by an admin.

GET

response

{
    "method": "GET",
    "error": null,
    "events": [
        {
            "_key": "<event_key>",
            "_index": "ame_default",
            "event_title": "<event_title>",
            "impact": "low",
            "urgency": "low",
            "priority": 0,
            "tenant_uid": "default",
            "assignee": "<assignee>",
            "search_name": "<saved_search>",
            "originQuery": {},
            "count": 2,
            "status": "<status_key>",
            "notifications": "<notifications_key>",
            "tags": [
                "<tag_one>",
                "<tag_two>"
            ],
            "notable_fields": [
                "<field_one>",
                "<field_two>"
            ],
            "most_recent": 1693400235.0321918,
            "first_seen": 1692881835.0320961,
            "event_ttl": -1,
            "alert_keys": [
                "<alert_key_one>",
                "<alert_key_two>",
            ]
        },
        { /* … */ }
    ]
}

POST

action create

request body

{
    "action": "create",
    "event": {
        "event_title": "<event_title>",
        "impact": "low|medium|high",
        "urgency": "low|medium|high",
        "priority": 0|1|2|3|4,
        "tenant_uid": "<tenant_uid>",
        "assignee": "<assignee>",
        "search_name": "<saved_search>",
        "originQuery": {
            "query_string": "<splunk_query>",
            "query_earliest": 1668009007,
            "query_latest": 1668012000,
        },
        "count": 2,
        "status": "<status_key>",
        "notifications": "<notifications_key>",
        "tags": [
            "<tag_one>",
            "<tag_two>"
        ],
        "notable_fields": [
            "<field_one>",
            "<field_two>"
        ],
        "most_recent": 1693400235.0321918,
        "first_seen": 1692881835.0320961,
        "event_ttl": -1,
        "alert_keys": [
            "<alert_key_one>",
            "<alert_key_two>",
        ]
    },
    "fields": {
        "user": "Bob",
        "src": "192.168.0.1",
        "etc": "my values"
    }
}

response body

{
    "method": "POST",
    "error": null,
    "event": { /* … */ }
}

action insert

request body

{
    "action": "insert",
    "event": {
        "_key": "<event_key>",
        "_index": "<tenant_index>",
        "event_title": "<event_title>",
        "impact": "low|medium|high",
        "urgency": "low|medium|high",
        "priority": 0|1|2|3|4,
        "tenant_uid": "<tenant_uid>",
        "assignee": "<assignee>",
        "search_name": "<saved_search>",
        "originQuery": {
            "query_string": "<splunk_query>",
            "query_earliest": 1668009007,
            "query_latest": 1668012000,
        },
        "count": 2,
        "status": "<status_key>",
        "notifications": "<notifications_key>",
        "tags": [
            "<tag_one>",
            "<tag_two>"
        ],
        "notable_fields": [
            "<field_one>",
            "<field_two>"
        ],
        "most_recent": 1693400235.0321918,
        "first_seen": 1692881835.0320961,
        "event_ttl": -1,
        "alert_keys": [
            "<alert_key_one>",
            "<alert_key_two>",
        ]
    },
}

response body

{
    "method": "POST",
    "error": null,
    "event": { /* … */ }
}

action update

request body

{
    "action": "update",
    "updateObject": {
        "attribute": "<event-attribute>",
        "value": "<new-value>"
    },
    "event": {
        "_key": "<event-key>",
        "tenant_uid": "<event-tenant_uid>"
    },
    "comment": "reason for update"
}

response body

{
    "method": "POST",
    "error": null,
    "event": { /* … */ }
}

action bulk-update

request body

{
    "action": "bulk-update",
    "updateObjects": [
        {
            "attribute": "<event-attribute>",
            "value": "<new-value>"
        },
        { … }
    ],
    "events": [
        {
            "_key": "<event-key>",
            "tenant_uid": "<event-tenant_uid>"
        },
        { … },
    ],
    "comment": "reason for update"
}

response body

{
    "method": "POST",
    "error": null,
    "entries": [ { /* … */ }, … ]
}

action comment

request body

{
    "action": "comment",
    "comment": "my comment on the matter",
    "event": {
        "_key": "<event-key>",
        "tenant_uid": "<event-tenant_uid>"
    }
}

response body

{
    "method": "POST",
    "error": null,
    "commentReply": True|False
}

/ame_tenants

https://localhost:8089/services/ame_tenants

Methods: GET, POST

Actions: create, init, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "tenants": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "tenant": {
        "tenant_uid": "<tenant_uid>",
        "name": "<Tenant Name>",
        "roles": [ "user", "power", "admin" ],
        "index": "<index_name>",
        "host": "<splunk_http_collector>",
        "port": "8088",
        "token": "fffefffe-fffe-fffe-fffe-fffefffefffe",
        "enable_ssl": true,
        "cacert": "-----BEGIN CERTIFICATE-----\nYOUR-CERTIFICATE-DATA\n-----END CERTIFICATE-----",
        "verify_ssl": true
    }
}

response

{
    'method': 'POST',
    'error': null,
    'tenant': { /* … */ }
}

action init

request

{
    "action": "init",
    "tenant": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "tenant": { /* … */ }
}

action update

request

{
    "action": "update",
    "tenant": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "tenant": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "tenant": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "tenant": { /* … */ }
}

/ame_workflow

https://localhost:8089/services/ame_workflow

Methods: POST

Actions: send

POST

request

{
    "action": "send",
    "uri": "https://mydomain:5050/endpoint",
    "body": {
        "key": "value"
    }
}

response

{
    "status_code": "<http_status_code>",
    "text": "<response_text>"
}

/ame_notifications

https://localhost:8089/services/ame_notifications

Methods: GET, POST

Actions: create, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "notifications": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "notification": {
        "name": "<my-notification-scheme>",
        "status_map": {
            "<status_key>" : [
                {
                    "action": "update",
                    "channel": "mail",
                    "info": {
                        "recipients": [ "receiver@ame.splunk" ],
                        "templateFilename": "default.html"
                    }
                }, 
                { /* … */ }
            ],
            "<status_key>" : [ { /* … */ } ]
        }
    }
}

response

{
    "method": "POST",
    "error": null,
    "notification": { /* … */ }
}

action update

request

{
    "action": "update",
    "notification": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "notification": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "notification": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "notification": { /* … */ }
}

/ame_statusoptions

https://localhost:8089/services/ame_statusoptions

Methods: GET, POST

Actions: create, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "status_options": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "status": {
        "state": "<status>",
        "description": "<description of the status>"
    }
}

response

{
    "method": "POST",
    "error": null,
    "status": { /* … */ }
}

action update

request

{
    "action": "update",
    "status": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "status": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "status": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "status": { /* … */ }
}

/ame_rules

https://localhost:8089/services/ame_rules

Methods: GET, POST

Actions: create, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "rules": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "rule": {
        "type": "single|multi",
        "name": "<rule_name>",
        "tenant_uid": "<tenant_uid>",
        "set_status": "<status_key>",
        "field": "count",
        "value": 11,
        "comparator": "gt|gte|lt|lte|eq|neq",
        "statement": "",
        "cron_schedule": "* * * * *",
        "from": "*|int",
        "to": "*|int",
        "sequence_number": 1
    }
}

response

{
    "method": "POST",
    "error": null,
    "rule": { /* … */ }
}

action update

request

{
    "action": "update",
    "rule": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "rule": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "rule": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "rule": { /* … */ }
}

/ame_templates

https://localhost:8089/services/ame_templates

Methods: GET, POST

Actions: create, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "templates": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "template": {
        "name": "<template_name>",
        "tenant_uid": "<tenant_uid>",
        "impact": "low|medium|high",
        "urgency": "low|medium|high",
        "default_assignee": "<user_name>",
        "notifications": "<notification_scheme_key>",
        "status": "<status_option_key>",
        "time_to_auto_resolve": 300,
        "tags": [ "<tag_one>", "<tag_two>" ],
        "notable_fields": [ "<field_one>", "<field_two>", "<field_three>" ],
        "append_alert": true,
        "notify_on_append": true,
        "editable": true
    }
}

response

{
    "method": "POST",
    "error": null,
    "template": { /* … */ }
}

action update

request

{
    "action": "update",
    "template": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "template": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "template": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "template": { /* … */ }
}

/ame_tags

https://localhost:8089/services/ame_tags

Methods: GET, POST

Actions: create, update, delete

GET

response

{
    "method": "GET",
    "error": null,
    "tags": "[ { … }, … ]"
}

POST

action create

request

{
    "action": "create",
    "tag": {
        "tag": "<tag>",
        "tenant_uid": "<tenant_uid>",
        "name": "<tag_name>",
        "description": "<tag_description>",
        "framework": "custom",
        "url": "<uri_link>",
    }
}

response

{
    "method": "POST",
    "error": null,
    "tag": { /* … */ }
}

action update

request

{
    "action": "update",
    "tag": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "tag": { /* … */ }
}

action delete

request

{
    "action": "delete",
    "tag": { /* … */ }
}

response

{
    "method": "POST",
    "error": null,
    "tag": { /* … */ }
}

Accessing the API using the Splunk REST Search Command

Following REST Endpoints are accessible through the Splunk rest search command.

info

Only GET requests are supported.

• ame_tenants
• ame_notifications
• ame_statusoptions
• ame_resolutions
• ame_rules
• ame_templates
• ame_tags

Example

| rest /services/ame_tenants