Network Policy API v1

Lets you block IP addresses within a specified IP CIDR block from accessing LCDN nodes for a set period of time.

Learn more:


Overview

This API allows the Aura Licensed CDN (LCDN) operator to programmatically block IP addresses associated with a specified IP CIDR block from accessing nodes on the LCDN for a pre-defined period of time. After the time expires, the IP addresses associated with the IP CIDR block will be unblocked.

This API enables LCDN operators to apply varying Time-to-Live (TTL) values for different blocks or sets and to see which blocklists are applied to the LCDN and the respective time slots for each. Operators can update and delete a blocklist if needed.

Who should use this API

A CDN operator can use this API to apply a list of IP addresses or CIDR blocks that they would like to be blocked from accessing the Aura LCDN for a specified period of time.

Get started

Before you use the Network Policy API for the first time:

  • You need to obtain an authorization token by creating and registering an application using the Aura Management Center (AMC) GUI. For detailed information about obtaining a token, see the “Managing OAuth2 Applications” section in the latest version of the Aura LCDN Administration Guide.

  • To enable this API, choose the API service named Network Policy, and set the access level to READ-WRITE.

  • Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support.

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Create a new blocklist POST /api/network-policy/v1/blocklists
List blocklists GET /api/network-policy/v1/blocklists
Get a blocklist GET /api/network-policy/v1/blocklists/{blockListId}
Update a blocklist PUT /api/network-policy/v1/blocklists/{blockListId}
Remove a blocklist DELETE /api/network-policy/v1/blocklists/{blockListId}
Get the blocklists global config GET /api/network-policy/v1/blocklists/config
Update the blocklists global config PUT /api/network-policy/v1/blocklists/config

Create a new blocklist

This operation creates a new blocklist.

POST /api/network-policy/v1/blocklists

Content-Type: application/json

Object type: Blocklist

Download schema: blocklist.create.schema.json

Request body:

{
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}

Status 201 application/json

Headers:

Location: https://akzz-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/api/network-policy/v1/blocklists/1

Object type: Blocklist

Download schema: blocklist.read-detailed.schema.json

Response body:

{
    "blockListId": 1,
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}
  1. Build a new Blocklist object.

  2. POST the object to /api/network-policy/v1/blocklists.

  3. The Location response header provides a link where you can GET the newly-created blocklist.

List blocklists

This operation returns a list of all configured blocklists.

GET /api/network-policy/v1/blocklists

Status 200 application/json

Object type: Blocklist

Download schema: blocklist.collection.schema.json

Response body:

{
    "blocklists": [
        {
            "blockListId": 1,
            "name": "SeaPirates1"
        },
        {
            "blockListId": 2,
            "name": "SeaPirates2"
        }
    ],
    "page": {
        "pageNumber": 1,
        "pageSize": 100,
        "totalPages": 1,
        "totalResults": 2
    }
}

Get a blocklist

This operation retrieves the details of a blocklist.

GET /api/network-policy/v1/blocklists/{blockListId}

Sample: /api/network-policy/v1/blocklists/1

Parameter Type Sample Description
URL path parameters
blockListId Integer 1 Uniquely identifies a blocklist.

Status 200 application/json

Object type: Blocklist

Download schema: blocklist.read-detailed.schema.json

Response body:

{
    "blockListId": 1,
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}
  1. Run the List blocklists operation to get a list of the configured blocklists. Store the blockListId of the relevant blocklist from the response.

  2. Make a GET request to /api/network-policy/v1/blocklists/{blockListId}.

  3. The operation responds with a Blocklist object.

Update a blocklist

This operation updates the details of a blocklist.

PUT /api/network-policy/v1/blocklists/{blockListId}

Sample: /api/network-policy/v1/blocklists/1

Content-Type: application/json

Object type: Blocklist

Download schema: blocklist.update.schema.json

Request body:

{
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}
Parameter Type Sample Description
URL path parameters
blockListId Integer 1 Uniquely identifies a blocklist.

Status 200 application/json

Object type: Blocklist

Download schema: blocklist.read-detailed.schema.json

Response body:

{
    "blockListId": 1,
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}
  1. Run the List blocklists operation to get a list of the configured blocklists. Store the blockListId of the relevant blocklist from the response.

  2. Make a GET request to /api/network-policy/v1/blocklists/{blockListId}.

  3. Modify the Blocklist object.

  4. PUT the object to /api/network-policy/v1/blocklists/{blockListId}.

  5. The operation responds with a Blocklist object.

Remove a blocklist

Remove a blocklist.

DELETE /api/network-policy/v1/blocklists/{blockListId}

Sample: /api/network-policy/v1/blocklists/1

Parameter Type Sample Description
URL path parameters
blockListId Integer 1 Uniquely identifies a blocklist.

Status 204

  1. To generate a list of all configured blocklists, make a GET request to /api/network-policy/v1/blockLists. Store the blockListId of the blocklist that you want to delete from the response.

  2. Make a DELETE request to /api/network-policy/v1/blocklists/{blockListId}.

Get the blocklists global config

This operation retrieves the global blocklists configuration parameter settings

GET /api/network-policy/v1/blocklists/config

Status 200 application/json

Object type: GlobalConfig

Download schema: blocklist-config.update.schema.json

Response body:

{
    "enableAutoPurgeExpired": false,
    "autoPurgeInterval": 300
}

Update the blocklists global config

This operation updates the global blocklist configuration parameters.

PUT /api/network-policy/v1/blocklists/config

Content-Type: application/json

Object type: GlobalConfig

Download schema: blocklist-config.update.schema.json

Request body:

{
    "enableAutoPurgeExpired": false,
    "autoPurgeInterval": 300
}

Status 200 application/json

Object type: GlobalConfig

Download schema: blocklist-config.update.schema.json

Response body:

{
    "enableAutoPurgeExpired": false,
    "autoPurgeInterval": 300
}
  1. Run the List blocklists operation to retrieve the global “blocklists” configuration settings. Store the response object.

  2. Modify the GlobalConfig object.

  3. PUT the object to /api/network-policy/v1/blocklists/config.

  4. The operation responds with a GlobalConfig object.

Data

This section describes the Network Policy API’s data objects that the API exposes.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

Blocklist

Blocklist update schema.

Download schema: blocklist.update.schema.json

Sample PUT request:

{
    "name": "SeaPirates",
    "description": "Pirates of the Caribbean",
    "endDate": "2020-03-11T20:30:00",
    "entries": [
        "1.1.1.1",
        "2.2.2.2",
        "172.19.116.131/24"
    ]
}

Blocklist members

Member Type Required Description
Blocklist: Blocklist update schema.
blockListId Integer Read-only. The system-generated unique ID for this blocklist.
description String A description of the blocklist.
endDate String The date in the future when the blocklist ends, expressed as an ISO 8601 timestamp. If the member is omitted or the value is set to an empty string, the corresponding entries are always blocked.
entries Array Lists up to 10,000 addresses to block in any combination of IPv4 and IPv6 addresses and CIDR block values.
name String The unique name for this blocklist.

GlobalConfig

Blocklists configuration update schema.

Download schema: blocklist-config.update.schema.json

Sample PUT request:

{
    "enableAutoPurgeExpired": false,
    "autoPurgeInterval": 300
}

GlobalConfig members

Member Type Description
GlobalConfig: Blocklists configuration update schema.
autoPurgeInterval Integer Auto purging interval in seconds.
enableAutoPurgeExpired Boolean Auto purging of expired blocklists enable/disable.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

For any error cases, the API responds with HTTP Problem JSON object with the application/problem+json media type. For example, when you try to GET a blocklist that does not exist, the API responds with a JSON object such as the following:

{
    "type":"https://localhost/api/network-policy/errors#core.entity-not-found",
    "title":"The requested entity could not be found",
    "detail":"BlockList 5 does not exist",
    "instance":"https://akzz-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/api/network-policy/v1/blocklists/5#3e0857adc3b1ab6",
    "entityType":"BlockList",
    "entityId":5
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
400 Bad Request.
401 Authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 The client doesn’t have the appropriate authority to perform the requested operation. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found.
405 Method not supported.
409 The operation couldn’t be completed due to a conflict with the current state of the resource. For example, when creating a blocklist with the name of an existing blocklist.
415 Unsupported media type.
503 Service is temporarily unavailable.