
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/ |
List Critical Events | GET | /prolexic-analytics/ |
Metrics | ||
List Metric Types | GET | /prolexic-analytics/ |
Get Metrics Data | POST | /prolexic-analytics/ |
Attack Reports | ||
List Attack Reports | GET | /prolexic-analytics/ |
Get an Attack Report | GET | /prolexic-analytics/ |
List events
List all events occurring in last 90 days on given contract.
GET /prolexic-analytics/
Example: /prolexic-analytics/
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/
Example: /prolexic-analytics/
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/
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/
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/
Example: /prolexic-analytics/
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/
Example: /prolexic-analytics/
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/cloud_security/prolexic_analytics/v1.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 |