AnswerX Name Controls OPEN API

Document created by Barry Greene Employee on Feb 23, 2017
Version 1Show Document
  • View in full screen mode

Introduction

For AnswerX Managed customers, this document covers the calls and work-flow follow when implementing AnswerX Name Controls through the Akamai OPEN RKS API (https://developer.akamai.com/).  AnswerX Licensed customers will follow a similar workflow direct against local on-net RKSs.


The documentation for the OPEN RKS API can be located at https://developer.akamai.com/api/dns/recursive-dns-db/overview.html.  This covers the general operation of the RKS API and is beyond the scope of this document.  For AnswerX Managed use cases, further reading about the Akamai OPEN API can be found here https://developer.akamai.com/ and example libraries can be found here https://github.com/akamai-open.  

 

The basic principles of using the AnswerX RKS are beyond the scope of this document but additional documentation can be obtained from an Akamai Account Manager or Support Engineer.

 

OPEN API Example

When working with the OPEN API an End User is provided with a unique hostname for the specific API they will be using.  They are also given a customer ID which will need to be added to the OPEN API URI.  The basic structure of the request URL is:

 

https:// [HOSTNAME] / [OPEN API PATH] / [CUSTOMER ID] / [END POINT]

 

ex.

https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/IPToSubscriberTable?key=174.16.2.214/32

Working with Subscriber IDs

The Subscriber ID can be either the Subscriber ID as given by DHCP/RADIUS or a combination of that ID plus the MAC Address of a specific device to be configured.  The ID + MAC ID is only used when Device Name Controls are enabled.  Please consult with your Akamai Support Engineer to ensure you are setup for Device Name Controls as it usually requires additional software enabled on Customer Premise Equipment (CPE).

Working Subscriber IDs and Devices

The Device Controls allow a Subscriber to create controls for a specific device within a household.  This requires an additional level of configuration on the part of the ISP and beyond the scope of this document, but please contact your Sales Representative for more information.  When working with Device Level Controls there is an additional layer of complexity to all API calls, since we have to create an additional row of settings for the Subscriber ID + Device MAC Address.  The API calls are the same, but the service expects the Key for each row to be “[SUBSCRIBER ID]-[MAC ADDRESS]”.  Substituting that value for the single Subscriber ID is all that is needed.

API Examples

NOTE:  When POST-ing values to the RKS API it is wise to set a VERY long Expiry or TTL.  The RKS operates with a Time-To-Live (TTL) associated with every row.  Often these settings are changed often enough that a problem is not encountered, but setting a TTL or 5 or 10 years is often recommended for important settings.  The Expiry/TTL is measured in seconds.


NOTE: The RKS has a limited number of Column Types that it supports STRING, INT, CIDR.  It is important to note that strings need to be wrapped in double quotes for the RKS to accept the value.  This is why you will see “key” wrapped in URL Encoded double quotes and you will see some values defined as “STRING” in the POST Body.  This lets the API know how to present the value to the RKS.  If presented incorrectly the RKS may return an invalid entry or bad separator error.

 

Working with the IP to Subscriber ID Mapping Table

Retrieving the Subscriber ID for an IP Address

HTTP Method: GET

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/IPToSubscriberTable?key=174.16.2.214/32

 

Updating the Subscriber ID for an IP Address

HTTP Method: POST

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/IPToSubscriberTable?key=174.16.2.214/32

POST Body:

{

 "Expiry": 86400,

 "Columns": [

   {"Value": "sean", "Type": "STRING"}

  ]

}

Removing the Subscriber ID for an IP Address

HTTP Method: DELETE

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/IPToSubscriberTable?key=174.16.2.214/32

 

Working with a Subscriber’s Block List

The Subscriber’s Block List is a static list of Domains that the Subscriber would want blocked regardless of the Parental Controls categories they have selected.  The use case for this table is NOT blocking Social Media, but wanting to block Snapchat.

 

NOTE: Please take note of the trailing DOT after the domain.  Since AnswerX is a recursive resolver it needs to validate domains from trailing dot that is often hidden by operating systems.

Retrieving the Block List for a Subscriber ID

HTTP Method: GET

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberBlacklist?key=%22sean%22

Updating the Block List for a Subscriber ID

HTTP Method: POST

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberBlacklist?key=%22sean%22

POST Body:

{

 "Expiry": 86400,

 "Columns": [

   {"Value": "facebook.com.,hello.com.", "Type": "STRING"}

  ]

}

Removing the Block List for a Subscriber ID

HTTP Method: DELETE

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberBlacklist?key=%22sean%22

 

Working with a Subscriber’s Allow List

The Subscriber’s Allow List is a static list of Domains that the Subscriber would want viewable regardless of the Parental Controls categories they have selected.  The use case for this table is blocking Social Media, but wanting to allow Facebook.  This does come with caveats of collateral domains to Facebook still being blocked.  Akamai can work with you to create a list of collateral domains when a user makes such a request.  

 

NOTE: Please take note of the trailing DOT after the domain.  Since AnswerX is a recursive resolver it needs to validate domains from trailing dot that is often hidden by operating systems.

Retrieving the Allow List for a Subscriber ID

HTTP Method: GET

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberWhitelist?key=%22sean%22

Updating the Allow List for a Subscriber ID

HTTP Method: POST

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberWhitelist?key=%22sean%22

POST Body:

{

 "Expiry": 86400,

 "Columns": [

   {"Value": "snapchat.com.,hello.com.", "Type": "STRING"}

  ]

}

Removing the Allow List for a Subscriber ID

HTTP Method: DELETE

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/SubscriberWhitelist?key=%22sean%22

Working with a Subscriber’s Category List

The Subscriber’s Category List is the List of Categories that the Subscriber would like blocked by AnswerX Name Controls.  You should work with your Akamai Account Manager to ensure the Category Names provided to the RKS API match what is internally configured.  A typo will cause a STRING to not match and be ignored.  The Category List (FilteringSubscribers) expects a comma separated list of categories to block.

Retrieving the Categories for a Subscriber ID

HTTP Method: GET

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribers?key=%22sean%22

Updating the Categories for a Subscriber ID

HTTP Method: POST

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribers?key=%22sean%22

POST Body:

{

 "Expiry": 86400,

 "Columns": [

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"}

  ]

}

Removing the Categories for a Subscriber ID

HTTP Method: DELETE

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribers?key=%22sean%22

Working with a Subscriber’s Time of Day Category List

The Subscriber’s Time of Day Category List is the List of Categories that the Subscriber would like blocked by AnswerX Name Controls on a specific day during a specific hour.  There are seven tables for Time of Day settings that correspond with the respective day being configured i.e. “FilteringSubscribersSunday.”  When configuring Time of Day Controls, it is not required that value is set for every day if that Day lacks any unique settings.  When AnswerX cannot locate a Subscriber ID in a Table, it falls back to that Subscriber’s FilteringSubscribers settings.

 

Each Time of Day table has 24 columns that represent each hour of the day.  When making an update to any of the Time of Day Tables each column must be defined.  You cannot set the value for a specific hour and ignore the other hours.

 

When setting the value for an hour you have the option of leaving the column empty “”, which AnswerX will interpret as fall back to the FilteringSubscribers settings.  If you wish to disable all filtering during that hour the hour should be set to “NONE” or any other placeholder value that is not a defined Filtering Category i.e. SOCIAL.

NOTE: List of all the Time of Day Tables

FilteringSubscribersSunday

FilteringSubscribersMonday

FilteringSubscribersTuesday

FilteringSubscribersWednesday

FilteringSubscribersThursday

FilteringSubscribersFriday

FilteringSubscribersSaturday

Retrieving the Categories for a Subscriber ID

HTTP Method: GET

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribersSunday?key=%22sean%22

Updating the Categories for a Subscriber ID

HTTP Method: POST

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribersSunday?key=%22sean%22

POST Body:

{

 "Expiry": 86400,

 "Columns": [

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "NONE", "Type": "STRING"},

   {"Value": "NONE", "Type": "STRING"},

   {"Value": "NONE, "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "PORNOGRAPHY,SOCIAL,MALWARE", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "", "Type": "STRING"},

   {"Value": "NONE", "Type": "STRING"},

   {"Value": "NONE", "Type": "STRING"},

   {"Value": "NONE", "Type": "STRING"}

  ]

}

Removing the Categories for a Subscriber ID

HTTP Method: DELETE

URL: https://akab-p66tvlmabo27boh7-xmv5rshfwct37kfk.dns.akamaiapis.net/recursive-dns-db/v1/service-instances/3/tables/FilteringSubscribersSunday?key=%22sean%22

Attachments

    Outcomes