Prolexic Analytics API v1

Retrieve analytics data from Prolexic DDoS protection and monitoring services.

Learn more:

Overview

The Prolexic Analytics API exposes analytics data from Prolexic DDoS protection and monitoring services such as alerts and network bandwidth timeseries data.

Headers

Authorization: EG1-HMAC-SHA256 client_token=[value];access_token=[value];timestamp=[value];nonce=[value];signature=[value]
  • This is RFC2616-standard, with proprietary specifics.
  • SDKs will be available for some languages.

Example:

Authorization: EG1-HMAC-SHA256 client_token=akaa-275ca6de04b11b91-cf46074bf3b52950;access_token=akaa-d6cfbdb2d0594ae4-ad000cf3a5473a08;timestamp=20130817T02:49:13+0000;nonce=dd9957e2-4fe5-48ca-8d32-16a772ac6d8f;signature=Q3uWyssCz9qsNxekOX+PXP0WrtGT+J5qd6ssN1UmUmw=

Design considerations

The API design is adapted from the data providers that power the dashboard and other analytics views on the Prolexic Portal.

Resources

Prolexic Analytics API exposes the Prolexic Portal Analytics data.

All reply body objects feature the following top-level members:

Member Type Description
status Boolean Indicates success or failure of the request.
statusMsg String Message indicating success or error.
currentContract String The name of the contract used in successful requests.
data Object or Array Result of a successful request.

API summary

Operation Method Endpoint
Events
List Events GET /prolexic-analytics/v1/events/contract/{contract}
List Critical Events GET /prolexic-analytics/v1/critical-events/contract/{contract}
Metrics
List Metric Types GET /prolexic-analytics/v1/metric-types
Get Metrics Data POST /prolexic-analytics/v1/metrics
Attack Reports
List Attack Reports GET /prolexic-analytics/v1/attack-reports/contract/{contract}/start/{start}/end/{end}
Get an Attack Report GET /prolexic-analytics/v1/attack-report/contract/{contract}/attack-id/{attackId}

List events

List all events occurring in last 90 days on given contract.

GET /prolexic-analytics/v1/events/contract/{contract}

Example: /prolexic-analytics/v1/events/contract/coral

Parameter Type Sample Description
Required
contract String coral Name of contract events should be attached to.

Status 200 application/json

Response:

{
    "status": true,
    "data": [
        {
            "service": "man",
            "eventInfo": {
                "location": "mia1",
                "lastOccurred": 1393236546,
                "attackId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems"
            },
            "eventType": "alert",
            "isOngoing": false,
            "eventStartTime": 1390975985,
            "eventTitle": "chkInt: Interface GigabitEthernet0/18 is down.",
            "severity": 80,
            "eventEndTime": 1393236546
        },
        {
            "service": "Mitigation",
            "eventInfo": {
                "eventTicketId": "70167",
                "attackType": "[\"SYN Flood\"]",
                "endTime": false,
                "attackEventId": "2707",
                "destinationIPs": "[178.132.240.114/32, 178.132.240.155/32, 178.132.240.203/32]",
                "startTime": 1392922838
            },
            "eventType": "attack",
            "isOngoing": true,
            "eventStartTime": 1392922838,
            "eventTitle": "[\"SYN Flood\"]",
            "severity": 100,
            "eventEndTime": 0
        }
    ],
    "current_contract": "coral",
    "status_msg": "Events acquired successfully"
}

List critical events

List critical events per contract that have started in the last 90 days.

GET /prolexic-analytics/v1/critical-events/contract/{contract}

Example: /prolexic-analytics/v1/critical-events/contract/coral

Parameter Type Sample Description
Required
contract String coral Name of contract events should be attached to.

Status 200 application/json

Response:

{
    "status": true,
    "data": [
        {
            "siteType": "DC",
            "source": "wbm",
            "location": "dca1",
            "ip": "192.216.61.102",
            "summary": "WBM TEST 5",
            "instance": "01",
            "interfaceName": "unknown",
            "count": 11,
            "siteCustomerName": "coral",
            "eventId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems",
            "siteName": "dca1",
            "acknowledged": 0,
            "state": 1,
            "recentOccur": 1395842910,
            "expires": 3600,
            "node": "lr1.dca1.plx",
            "importance": 5,
            "notes": "TEST 5",
            "firstOccur": 1393657985,
            "description": "TEST WBM LEVEL 5"
        }
    ],
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully"
}

List metric types

GET /prolexic-analytics/v1/metric-types

Status 200 application/json

Response:

{
    "status": true,
    "data": {
        "routed": {
            "metrics": {
                "bandwidthIn": { "desc": "Customer inbound traffic, bits per second" },
                "packetsIn": { "desc": "Customer inbound traffic, packets per second" }
            }
        },
        "connect": {
            "metrics": {
                "bandwidthIn": { "desc": "Customer inbound traffic, bits per second" },
                "packetsIn": { "desc": "Customer inbound packets, packets per second" }
            }
        },
        "mitigationPost": {
            "metrics": {
                "packets": { "desc": "Customer traffic packets per second" },
                "bandwidth": { "desc": "Customer traffic bits per second" }
            }
        },
        "proxy": {
            "metrics": {
                "latency": { "desc": "Average latency of request" },
                "bandwidthIn": { "desc": "Customer inbound traffic, bits per second" },
                "bandwidthOut": { "desc": "Customer outbound traffic, bits per second" },
                "connections": { "desc": "Connections count" },
                "packetsOut": { "desc": "Customer outbound traffic, packets per second" },
                "requests": { "desc": "Requests count" },
                "packetsIn": { "desc": "Customer inbound traffic, packets per second" }
            }
        },
        "mitigationPre": {
            "metrics": {
                "packets": { "desc": "Customer traffic packets per second" },
                "bandwidth": { "desc": "Customer traffic bits per second" }
            }
        },
        "fbm": {
            "metrics": {
                "bandwidth": {
                    "desc": "Customer traffic bits per second",
                    "subnets": [ "1.1.2.0/24" ],
                    "protocols": [ "total", "icmp", "igmp", "udp", "tcp" ]
                },
                "packets": {
                    "desc": "Customer traffic packets per second",
                    "subnets": [ "1.1.2.0/24" ],
                    "protocols": [ "total", "icmp", "igmp", "udp", "tcp" ]
                }
            }
        }
    },
    "currentContract": "coral",
    "statusMsg": "Metric Types list acquired successfully"
}

Get metrics data

List metrics specified in type object falling between given start and end times, sampled at given rate and attached to given contract. The maximum range between start and end is 90 days.

If some (not all) requested types are invalid, invalid types are silently dropped, and the response only contains data for valid requests. More meaningful errors result if requesting data for only one type at a time.

POST /prolexic-analytics/v1/metrics

Content-Type: application/json

Request:

{
    "contract": "venus",
    "start": 1322390037,
    "end": 1400385899,
    "samples": 100,
    "type": {
        "routed": [ "bandwidthIn" ],
        "fbm": [
            {
                "metric": "bandwidth",
                "protocol": "total",
                "subnet": "1.1.1.0/24"
            },
            {
                "metric": "packets",
                "protocol": "tcp",
                "ip": "1.1.1.10"
            }
        ]
    }
}

Status 200 application/json

Response:

{
    "status": true,
    "data": [
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "points": [
                [ 1392609960, 211014 ],
                [ 1396886760, 202529 ]
            ]
        },
        {
            "service": "fbm",
            "metric": "bandwidthIn",
            "protocol": "total",
            "subnet": "1.1.1.0/24",
            "points": [
                [ 1392609960, 211014 ],
                [ 1396886760, 202529 ]
            ]
        },
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "protocol": "tcp",
            "ip": "1.1.1.10",
            "points": [
                [ 1392609960, 211014 ],
                [ 1396886760, 202529 ]
            ]
        }
    ],
    "currentContract": "coral",
    "statusMsg": "Metrics acquired successfully"
}

Request body objects feature the following members:

Member Type Description
contract String Name of contract to which metrics apply.
start Number Unix timestamp for beginning of metrics search.
end Number Unix timestamp for end of metrics search.
samples Number Integer value from 2 to 1000.
type Object Represents desired metrics. See below.

The following shows a type object:

{
    "routed": [ "bandwidthIn" ],
    "mitigationPre": [ "packets", "bandwidth" ],
    "fbm": [
        {
            "metric": "bandwidth",
            "protocol": "total",'
            "subnet": "1.1.2.0/24"
        },
        {
            "metric": "packets",
            "protocol": "tcp",
            "ip": "1.1.1.1"
        }
    ]
}

List attack reports

List attack events per contract, limited to last 90 days.

GET /prolexic-analytics/v1/attack-reports/contract/{contract}/start/{start}/end/{end}

Example: /prolexic-analytics/v1/attack-reports/contract/coral/start/1397049511/end/1399641518

Parameter Type Sample Description
Required
contract String coral Name of contract attack reports belong to.
end Number 1399641518 Unix timestamp for end of attack report search.
start Number 1397049511 Unix timestamp for beginning of attack report search.

Status 200 application/json

Response:

{
    "status": true,
    "data": [
        {
            "attackId": 2985,
            "destinationPort": "80",
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17277,
                    "bandwidth": 6500000000,
                    "pps": 700000
                },
                {
                    "location": "HKG",
                    "peakId": 17276,
                    "bandwidth": 3000000000,
                    "pps": 600000
                }
            ],
            "eventStartTime": 1381320180,
            "ticketId": 97585,
            "eventEndTime": 1381349454,
            "eventStartTimeAsString": "2013-10-09 12:03:00",
            "endTime": 1381363451,
            "eventId": 4202,
            "eventEndTimeAsString": "2013-10-09 20:10:54",
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.100"
                },
                {
                    "netmask": 32,
                    "ip": "178.132.240.155"
                }
            ],
            "startTime": 1381063041,
            "eventTypes": [
                "DNS Flood",
                "ICMP Flood",
                "UDP Fragment"
            ]
        },
        {
            "attackId": 2974,
            "destinationPort": "80",
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17093,
                    "bandwidth": 300000000,
                    "pps": 200
                },
                {
                    "location": "HKG",
                    "peakId": 17092,
                    "bandwidth": 3000000,
                    "pps": 1000
                }
            ],
            "eventStartTime": 1380714180,
            "ticketId": 97368,
            "eventEndTime": 1380752215,
            "eventStartTimeAsString": "2013-10-02 11:43:00",
            "endTime": 1380847367,
            "eventId": 4170,
            "eventEndTimeAsString": "2013-10-02 22:16:55",
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.126"
                }
            ],
            "startTime": 1380714180,
            "eventTypes": [ "SYN Flood" ]
        }
    ],
    "currentContract": "coral",
    "statusMsg": "Attack reports acquired successfully"
}

Get an attack report

Get full details of an attack report. Attack must be assigned to the given contract.

GET /prolexic-analytics/v1/attack-report/contract/{contract}/attack-id/{attackId}

Example: /prolexic-analytics/v1/attack-report/contract/coral/attack-id/1966

Parameter Type Sample Description
Required
attackId Number 1966 Integer matching the attackId of the attack desired.
contract String coral Name of contract attack report belong to.

Status 200 application/json

Response:

{
    "status": true,
    "data": [
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18594,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "SJC",
            "endTime": 1390261538,
            "eventBw": 500000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 1200,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        },
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18595,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "LON",
            "endTime": 1390261538,
            "eventBw": 90000000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 200000,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        }
    ],
    "currentContract": "coral",
    "statusMsg": "Attack report acquired successfully"
}

Errors

Responses from the API include status and statusMsg parameters indicating the success or failure of a request. For a failed request, the status boolean will be set to false and statusMsg will contain a string explaining the error condition, such as in the following example:

{
    "status": false,
    "statusMsg": "Description of failure"
}

For non–2xx HTTPS returned status codes, the error JSON below is returned as outlined. (See below for a list of error codes.)

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Reply Body:
{
    "type": "https://developer.akamai.com/api/luna/prolexic-analytics/overview.html#ratelimiting"
    "title": "Too many requests"
    "status" : 429,
    "detail": "additional non-http specific info where relevant"
}

Rate limiting–429 status

Prolexic Analytics API endpoints are subject to a rate-limiting constraint, which is currently set to 1000 requests per hour. When this limit is reached, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop. This is consistent with all protected Akamai assets exposed via API calls.

Response codes

Code Description
200 OK
201 Created/OK
202 OK accepted
204 No changes
400 Bad input parameter. Error message should indicate which one and why
401 Authentication failure
403 Authorization failure
404 Resource not found
405 Request method not expected (generally should be GET or PUT)
409 Conflict
410 Requested resource is no longer available
411 Content-length header not specified
413 Request body exceeds maximum allowable size
423 Requested resource is locked
429 Too many requests
500 Internal server error unexpected condition
501 Not supported
503 Too many requests; service is temporarily unavailable
507 Data size is over allowable limit