Firewall Rules Notification API v1
Subscribe yourself and others to CIDR block changes and retrieve CIDR blocks to include in your firewall rules.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
Akamai periodically refreshes edge server IP addresses for routine maintenance. With Firewall Rules Notification, you can manage who receives email notifications about the planned changes. Akamai provides two to five weeks of advance notice before activating the IP addresses.
It’s important that you update your company’s firewall to accept traffic from new IP addresses, or remove access to decommissioned ones. Keeping your firewall rules current ensures that requests served through the IPs listed in our CIDR blocks reach your origin.
The Firewall Rules Notification API lets you:
- subscribe or unsubscribe users to notifications for specific services.
- retrieve subscription and service information.
- view CIDR block information required to update your firewall rules.
This API provides you with a programmatic interface to the same functionality available in Akamai Control Center.
Who should use this API
Use this API if you manage your company’s firewall. Programmatically retrieve Akamai CIDR block details to add or remove addresses in your firewall rules. You can also automate subscription settings that define who receives email notifications about upcoming changes to the CIDR blocks.
Getting started
Before using FRAPI for the first time:
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named Firewall Rules Notification, and set the access level to READ-WRITE.
Resources
The following lists unique concepts for this API:
Activation date in the Control Center application is the same thing as the effective date in the API.
CIDRs with a status of
Deleted
are still visible in response objects.Deleted
for this API means that CIDR block is no longer in use and no longer serves traffic to your origin. You can remove that CIDR block from your firewall rules.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
List services | GET | /firewall-rules-manager/ |
Get a service | GET | /firewall-rules-manager/ |
List CIDR blocks | GET | /firewall-rules-manager/ |
List subscriptions | GET | /firewall-rules-manager/ |
Update subscriptions | PUT | /firewall-rules-manager/ |
Add or remove subscriptions | PATCH | /firewall-rules-manager/ |
List services
Get a list of services you are subscribed to. To see additional services, subscribe to them first and run the operation again.
GET /firewall-rules-manager/
Status 200
application/json
Object type: Service
Download schema: services.json
Response body:
[
{
"serviceId": 3,
"serviceName": "TestIP",
"description": "Test IPs"
},
{
"serviceId": 4,
"serviceName": "TestIP again",
"description": "Test IPs"
}
]
Make a GET request to
/
.firewall-rules-manager/ v1/ services The response is an array of Service objects. Locate a
serviceID
and save it for later use.
Get a service
Get information about a specific service.
GET /firewall-rules-manager/
Sample: /firewall-rules-manager/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
serviceId |
Integer | 3 |
A unique identifier for a service. |
Status 200
application/json
Object type: Service
Download schema: service.json
Response body:
{
"serviceId": 3,
"serviceName": "TestIP",
"description": "Test IPs"
}
Run List services and choose a service from the array. Store the
serviceId
for later use.Make a GET request to
/
.firewall-rules-manager/ v1/ services/ {serviceId} The response is a Service object.
List CIDR blocks
List all CIDR blocks for all services you are subscribed to. To see additional CIDR blocks, subscribe yourself to more services and run this operation again.
GET /firewall-rules-manager/
Sample: /firewall-rules-manager/
Parameter | Type | Sample | Description |
---|---|---|---|
Optional query parameters | |||
effectiveDateGt |
String | 2017-02-21 |
The ISO 8601 date the CIDR block starts serving traffic to your origin. Ensure your firewall rules are updated to allow this traffic to pass through before the effective date. |
lastAction |
Enumeration | add |
Whether a CIDR block was added, updated, or removed from service. You can use this parameter as a sorting mechanism and return only CIDR blocks with a change status of add , update , or delete . Note that a status of delete means the CIDR block is no longer in service, and you can remove it from your firewall rules. |
Status 200
application/json
Object type: CidrBlock
Download schema: cidrBlocks.json
Response body:
[
{
"cidrId": 13742,
"serviceId": 9,
"serviceName": "PERF_ANALYTICS",
"cidr": "66.171.230.134",
"cidrMask": "/32",
"port": "80,443",
"creationDate": "2017-02-21",
"effectiveDate": "2017-02-21",
"changeDate": "2017-02-21",
"minIp": "66.171.230.134",
"maxIp": "66.171.230.134",
"lastAction": "add"
}
]
List subscriptions
List subscriptions you created for yourself and other users. You can only see the subscription information for configurations you created yourself. If someone else subscribed you to a service, you won’t see that subscription returned by this operation.
GET /firewall-rules-manager/
Status 200
application/json
Object type: Subscription
Download schema: subscriptions.json
Response body:
{
"subscriptions": [
{
"subscriptionId": 1,
"serviceId": 13,
"serviceName": "Test IPs",
"createdBy": "username",
"email": "mp@mail.com",
"signupDate": "2017-03-28"
},
{
"subscriptionId": 2,
"serviceId": 15,
"serviceName": "CCUAPI",
"createdBy": "username2",
"email": "abcd@akamai.com",
"signupDate": "2017-10-11"
}
]
}
Make a GET request to
/
.firewall-rules-manager/ v1/ subscriptions The response is an array of Subscription objects.
Update subscriptions
Subscribe or unsubscribe users to services.
PUT /firewall-rules-manager/
Content-Type: application/json
Object type: Subscription
Download schema: subscriptionPutRequests.json
Request body:
{
"subscriptions": [
{
"serviceId": 13,
"email": "mp@mail.com"
},
{
"serviceId": 15,
"email": "abcd@akamai.com"
}
]
}
Status 200
application/json
Object type: Subscription
Download schema: subscriptions.json
Response body:
{
"subscriptions": [
{
"subscriptionId": 1,
"serviceId": 13,
"serviceName": "Test IPs",
"createdBy": "username",
"email": "mp@mail.com",
"signupDate": "2017-03-28"
},
{
"subscriptionId": 2,
"serviceId": 15,
"serviceName": "CCUAPI",
"createdBy": "username2",
"email": "abcd@akamai.com",
"signupDate": "2017-10-11"
}
]
}
Run List subscriptions.
The response is an array of Subscription objects. Modify the array of objects.
PUT the modified object back to
/
.firewall-rules-manager/ v1/ subscriptions
Add or remove subscriptions
Subscribe or unsubscribe users to services.
PATCH /firewall-rules-manager/
Content-Type: application/json
Object type: Subscription
Download schema: subscriptionPatchRequests.json
Request body:
{
"subscriptions": [
{
"op": "add",
"path": "/",
"serviceId": 13,
"email": "mp@mail.com"
},
{
"op": "remove",
"path": "/15"
}
]
}
Status 200
application/json
Object type: Subscription
Download schema: subscriptions.json
Response body:
{
"subscriptions": [
{
"subscriptionId": 1,
"serviceId": 13,
"serviceName": "Test IPs",
"createdBy": "username",
"email": "mp@mail.com",
"signupDate": "2017-03-28"
},
{
"subscriptionId": 2,
"serviceId": 15,
"serviceName": "CCUAPI",
"createdBy": "username2",
"email": "abcd@akamai.com",
"signupDate": "2017-10-11"
}
]
}
Create a request object with an empty
subscriptions
array.If you want to add a set of subscriptions:
Run List services and collect the
serviceId
value for the service you want to subscribe the users to.For each new subscription:
- Add an object to the
subscriptions
array. - Specify the
op
member asadd
. - Specify the
path
to thesubscriptionId
as a blank/
. - Specify the
serviceId
of the service you want to subscribe to. - Specify the
email
address of the user you want to subscribe.
- Add an object to the
If you want to remove a set of subscriptions:
Run List subscriptions and collect the
subscriptionId
values you want to remove.For each subscription you want to remove:
Add an object to the
subscriptions
array.Specify the
op
member asremove
.Specify the
path
to as/
followed by asubscriptionId
you want to remove.
PATCH the request object with added and removed subscriptions to
/
.firewall-rules-manager/ v1/ subscriptions
Data
This section provides details for each type of data object the API exchanges.
Download the JSON schemas for this API.
Subscription
Displays subscriptions for a service.
Download schema:
subscription.json
Sample GET response:
{
"subscriptions": [
{
"subscriptionId": 1,
"serviceId": 13,
"serviceName": "Test IPs",
"createdBy": "username",
"email": "mp@mail.com",
"signupDate": "2017-03-28"
},
{
"subscriptionId": 2,
"serviceId": 15,
"serviceName": "CCUAPI",
"createdBy": "username2",
"email": "abcd@akamai.com",
"signupDate": "2017-10-11"
}
]
}
Subscription members
Member | Type | Description |
---|---|---|
Subscription : Displays subscriptions for a service. |
||
createdBy |
String | A username who created a subscription. |
email |
String | The email of the user subscribed to a service and receiving notifications about the CIDR block updates. |
serviceId |
Integer | A unique identifier for a service. |
serviceName |
String | The name of a service. This is often the same as the product you purchased. |
signupDate |
String | The date a subscriber signed up for notifications. The date is in ISO format. |
subscriptionId |
Integer | A unique identifier for a subscription. |
Service
Specifies service information.
Download schema:
service.json
Sample GET response:
{
"serviceId": 3,
"serviceName": "TestIP",
"description": "Test IPs"
}
Service members
Member | Type | Description |
---|---|---|
Service : Specifies service information. |
||
description |
String | A description of the service. |
serviceId |
Integer | A unique identifier for a service. |
serviceName |
String | The name of a service. This is often the same as the product you purchased. |
CidrBlock
Describes CIDR blocks and the services they belong to.
Download schema:
cidrBlock.json
Sample GET response:
[
{
"cidrId": 13742,
"serviceId": 9,
"serviceName": "PERF_ANALYTICS",
"cidr": "66.171.230.134",
"cidrMask": "/32",
"port": "80,443",
"creationDate": "2017-02-21",
"effectiveDate": "2017-02-21",
"changeDate": "2017-02-21",
"minIp": "66.171.230.134",
"maxIp": "66.171.230.134",
"lastAction": "add"
}
]
CidrBlock members
Member | Type | Description |
---|---|---|
CidrBlock : Describes CIDR blocks and the services they belong to. |
||
changeDate |
String | The ISO 8601 date when a CIDR block was last updated. |
cidr |
String | A list of IP addresses belonging to Akamai edge servers for a particular service. |
cidrId |
Integer | A unique identifier for a CIDR block. |
cidrMask |
Enumeration | Indicates the range (start and end IP) of a CIDR block. /32 and /64 denote whether the IP addresses in the CIDR block are IPv4 or IPv6, respectively. |
creationDate |
String | The ISO 8601 date the CIDR block was created. |
effectiveDate |
String | The ISO 8601 date the IP addresses start passing traffic. Make sure your firewall rules are updated to accept traffic before this date. The date is typically two weeks after the CIDR block’s creation date. |
lastAction |
Enumeration | The last Action, or change, made to a CIDR block. Either add , update , or delete . |
maxIp |
String | The maximum IP is the top of the range for the CIDR block. |
minIp |
String | The minimum IP is the base of the range for the CIDR block. |
port |
String | The set of comma-delimited ports through which your server receives traffic from Akamai servers. |
serviceId |
Integer | A unique identifier for a service. |
serviceName |
String | The name of a service. This is often the same as the product you purchased. |
Errors
This section tells you about the Firewall Rules Notification API’s error response format, and details the range of HTTP status codes the API produces.
Error responses
The Identity Management API responds with HTTP problem error objects that provide details useful for debugging.
The following shows a typical error response. The outer object
characterizes the overall problem, while the details
array lists
potentially more than one problem detected in the request.
{
"type" : "/firewall-rules-manager/error-types/5",
"status" : 404,
"title" : "ServiceId doesn't exist",
"detail" : "ServiceId: 233 not found",
"instance" : "",
"errors" : [ ]
}
HTTP status codes
This section lists the range of HTTP response codes the API may produce for both success and error cases:
Code | Description |
---|---|
200 | Request OK. |
302 | The requested item is temporarily available at the link provided. |
400 | Bad Request. |
401 | Authentication failure. |
403 | Access Denied. |
404 | Resource not found. |
405 | Method not supported. |
415 | Unsupported media type. |
500 | Internal server error. |
502 | Platform timeout error. |
503 | Too many requests. Service is temporarily unavailable. |