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