Configure custom DNS behavior based on rules stored in Akamai’s Reputation Knowledge Server (RKS).

Learn more:

• AnswerX

Overview

AnswerX is an intelligent, recursive DNS platform and product designed to manage DNS traffic. AnswerX is subscriber-aware, which allows users to offer value-added service options such as parental controls and fast access to preferred websites while enhancing the user’s ability to deliver better, faster service to subscribers. AnswerX can process millions of DNS transactions per second and offers best-in-class total cost of ownership. There are three versions of AnswerX:

• AnswerX Licensed runs in the carrier’s network and Akamai provides system support.

• AnswerX Cloud is a cloud service managed and maintained using Akamai’s network. This has the advantage of requiring few resources from a customer. The configuration uses Akamai rack space, power, and other related equipment. The service will still be configured individually per customer, but it will run on shared capacity in locations where Akamai believes it is the most effective.

• AnswerX Managed completely manages the servers in the carrier’s network and customers do not have access to the systems. This has the advantage of being dedicated capacity. Since it runs in the carrier network, it can be deployed close to the end clients to provide the best possible DNS resolution times.

The AnswerX RKS API lets you configure custom DNS behavior based on rules. These rules are stored in the Reputation Knowledge Server (RKS). RKS is a distributed database containing two types of tables, “static” and “real-time” (RTT). Certain API calls only work on one type of table or the other as indicated below.

You can call this API with two different URI schema types. The first type assumes that the caller knows their service instance ID. The second type requires only the product’s name (for example, managed or cloud) and the contract ID. Both formats have the same behavior and are documented here.

For API calls that have a key field, the key is always matched against the first column in the table (that is, the leftmost column is the key column). If the key column is of type STRING, then the key in the URI must be enclosed in URI-encoded double quotes (%22KEY%22).

Who should use this API

This API is for site administrators, project managers, and technical support providers who will implement AnswerX for your organization. It assumes that you have a working knowledge of AnswerX and how it uses RKS data. If you are not familiar with these topics, see the AnswerX product page.

Getting started

• Review Get Started to familiarize yourself with Akamai APIs.

• Visit the akamai-open repository to download reference EdgeGrid clients and sample code.

• Review Authorize Your Client to create your access credentials and authorizations, making sure you enable read access for the AnswerX RKS API.

• Get help from the Akamai developer community.

The Recursive DNS DB API lets users of RKS view, modify, add, and delete data in their RKS tables. For more information about AnswerX and RKS, see the AnswerX product page.

The RKS table system is a part of Akamai’s AnswerX Recursive Nameserver product. This API lets users make changes to their RKS tables, including viewing table contents, viewing individual rows, and, for dynamic tables, adding, modifying, and deleting rows.

The API supports XML and JSON data formats. JSON is the default. To update or add a new row in a table, your JSON or XML should contain a list of all non-key columns, with the type and new value of each column listed. You may also provide an optional Expiry field, which specifies a time-to-live for the row, in seconds. The allowed column types are INT, UINT64, STRING, or CIDR.

For all REST methods (GET, PUT/POST, and DELETE), there are two ways to access your data: instance ID or product type and contract ID. Assuming the table to be accessed is named TABLE, the URL format for these, respectively, is:

/recursive-dns-db/v1/service-instances/ID/tables/TABLE/...
/recursive-dns-db/v1/product-types/PROD/contracts/CID/recursive-db/tables/TABLE

The key column is given as part of the URL (for complete details on the JSON and XML formats, and the REST calls, see the Resources section.

For example, you have a dynamic table called IPToSubscriber. The key field for this table is an IP address in CIDR notation, and there are five other columns. To update a row for 1.2.3.4/32, for service instance ID 20 using JSON, you might submit the following:

PUT /recursive-dns-db/v1/service-instances/20/tables/IPToSubscriberTable?key=1%2E2%2E3%2E4%2F32 HTTP/1.1
Content-type: application/json
Content-length: 268

{
    "Columns": [
        {
            "Type": "STRING",
            "Value": "This is my first string"
        },
        {
            "Type": "INT",
            "Value": "100"
        },
        {
            "Type": "INT",
            "Value": "200"
        },
        {
            "Type": "INT",
            "Value": "300"
        },
        {
            "Type": "STRING",
            "Value": "AnotherStringHere"
        }
    ],
    "Expiry": 86400
}

The same row update in XML format will look like this:

PUT /recursive-dns-db/v1/service-instances/20/tables/IPToSubscriberTable?key=1%2E2%2E3%2E4%2F32 HTTP/1.1
Content-type: application/xml
Content-length: 350

<Row>
  <Columns>
    <Column>
       <Value>This is my first string</Value>
       <Type>STRING</Type>
    </Column>
    <Column>
       <Value>100</Value>
       <Type>INT</Type>
    </Column>
    <Column>
       <Value>200</Value>
       <Type>INT</Type>
    </Column>
    <Column>
       <Value>300</Value>
       <Type>INT</Type>
    </Column>
    <Column>
       <Value>AnotherStringHere</Value>
       <Type>STRING</Type>
    </Column>
  </Columns>
  <Expiry>86400</Expiry>
</Row>

You can also fetch data with a GET request or delete data with a DELETE request. For GET, indicate your preferred format (JSON or XML) in the Accept header. If you omit the header, the format defaults to JSON.

Resources

The AnswerX API lets you interact with table data using two different endpoints whose responses are formatted identically. One assumes you know the unique service instance identifier, and the other requires only the contract identifier and product name, such as managed or cloud.

API operations specify table rows with a unique key parameter, which matches the value in the first column of the row. String values must be double-quoted then URL-encoded, for example %22KEY%22.

POST operations that reference a new key add rows to the table, otherwise they modify existing rows.

DELETE operations remove existing rows. The key is required for DELETE. Deletions are always per-row, never the entire table.

The action and table_type parameters do not apply to POST or DELETE operations. They only apply to the GET operations enumerated below (dump, dump-data-only, schema, and subscribe). All GET operations besides those four are per-row and require a key parameter but not an action or table_type.

• dump: Reports the full contents of a table, either for a static, dynamic, or rtt table in read-only format. It does not modify a table’s contents. Leave out the ‘key’ parameter as it refers to a specific table row. For static tables, the schema is included. If the table_type is rtt, you must include &table_type=rtt in the URL.

• dump-data-only: Reports the full contents of a table as above, but lists the data in a minimal text format. Leave out the ‘key’ parameter as it refers to a specific table row.

• schema: Generates a description of the requested table data. Note that this data does not follow the more formal XML or JSON schema format.

• subscribe: Generates table metadata up to the current sync point, usually equivalent to the table schema. This only applies to dynamic table types.

The key required for POST, DELETE, and per-row GET operations. For other operations, do not specify a key since the operation returns the whole table (the key is not omitted but not applicable because the operation returns the entire table).

The table_type parameter is only needed if calling dump or dump-data-only on a dynamic table. In those cases, specify table_type=dynamic or table_type=rtt. You can specify table_type=static but static is the default, so it is optional. These are the only cases where table_type is needed. This parameter does not work with POST or DELETE operations.

The table_type parameter is only needed if calling “dump” or “dump-data-only” on a dynamic table. In those cases, specify table_type=dynamic or table_type=rtt. You can specify table_type=static but static is the default, so it is optional. These are the only cases where table_type is needed.

See the Get Row or Table by Service Instance or Get Row or Table by Product Type operations for samples of this alternative output.

API summary

Get row or table by service instance

This operation gets data for a row with a unique service instance ID. For rows it works on both static and RTT tables. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).

<Row>
    <Key>127.0.0.1</Key>
    <Columns>
        <Column>
            <Value>127.0.0.1</Value>
        </Column>
        <Column>
            <Value>Utah</Value>
        </Column>
    </Columns>
</Row>

{
    "Key": "127.0.0.1",
    "Columns": [
        { "Value": "Utah" },
        { "Value": "127.0.0.1" }
    ]
}

The following shows the alternate response format when the action is set to schema or subscribe. Each field’s Name is a valid key with which to access a table row.

<Schema>
    <Field>
        <Name>HostIP</Name>
        <Type>CIDR</Type>
    </Field>
    <Field>
        <Name>SubscriberID</Name>
        <Type>STRING</Type>
    </Field>
</Schema>

The following shows the alternate response format when the action is set to dump. The MetaData section and each Field contain lines of key/value pairs rather than structured XML. The trailing lines after the MetaData section represent the table’s raw data separately available when the action is dump-data-only.

<Schema>
    <Field>
        Name: MyKey
        Type: STRING
    </Field>
    <Field>
        Name: v4Mask
        Type: UINT64
    </Field>
    <Field>
        Name: v6Mask
        Type: UINT64
    </Field>
    <Field>
        Name: MyVal
        Type: STRING
    </Field>
    <Field>
        Name: MyCidr
        Type: CIDR
    </Field>
</Schema>

<MetaData>
    TableType: INDEXED
    TableVersion: 6241959731729006595
</MetaData>
    "Michelangelo" 32 128 "Donatello" 5.6.7.8/32
    "Raphael" 24 96 "Leonardo" 127.0.0.1/32

Add or update row by service instance

The request must specify the row’s data, formatted as XML or JSON. The optional Expiry data member is a time interval in seconds after which the row expires: if no expiry is given, the row does not expire. This method only applies to RTT tables.

The key column is matched against the leftmost column in the table. If it matches an existing row, that row is updated. Otherwise, a new row is added. Note that key is considered to be the value of the leftmost row: thus, the XML or JSON you submit in the body of your request should not contain a field for the leftmost key column: only for the subsequent columns.

In the following example the table is assumed to have two columns. The first one is updated by using the key field, and the second one is a string column whose new value will be Arizona.

<Row>
    <Columns>
        <Column>
            <Value>Arizona</Value>
            <Type>STRING</Type>
        </Column>
    </Columns>
    <Expiry>60</Expiry>
</Row>

{
    "Expiry": 60,
    "Columns": [
        {
            "Value": "Arizona",
            "Type": "STRING"
        }
    ]
}

Remove row by service instance

This operation lets you delete a row from a table with a service instance ID. It only applies to RTT tables. The row to be deleted must have a leftmost key column whose value matches key.

Get row or table by product type

This operation gets data for a row with a unique product name and contract ID. For rows it works on both static and RTT tables. If no rows have a key column matching this string, an error will be returned. If the key column is of type STRING, then the key must be enclosed in URL-encoded double quotes (%22key%22).

<Row>
    <Key>127.0.0.1</Key>
    <Columns>
        <Column>
            <Value>127.0.0.1</Value>
        </Column>
        <Column>
            <Value>Utah</Value>
        </Column>
    </Columns>
</Row>

{
    "Key": "127.0.0.1",
    "Columns": [
        { "Value": "Utah" },
        { "Value": "127.0.0.1" }
    ]
}

The following shows the alternate response format when the action is set to schema or subscribe. Each field’s Name is a valid key with which to access a table row.

<Schema>
    <Field>
        <Name>HostIP</Name>
        <Type>CIDR</Type>
    </Field>
    <Field>
        <Name>SubscriberID</Name>
        <Type>STRING</Type>
    </Field>
</Schema>

The following shows the alternate response format when the action is set to dump. The MetaData section and each Field contain lines of key/value pairs rather than structured XML. The trailing lines after the MetaData section represent the table’s raw data separately available when the action is dump-data-only.

<Schema>
    <Field>
        Name: MyKey
        Type: STRING
    </Field>
    <Field>
        Name: v4Mask
        Type: UINT64
    </Field>
    <Field>
        Name: v6Mask
        Type: UINT64
    </Field>
    <Field>
        Name: MyVal
        Type: STRING
    </Field>
    <Field>
        Name: MyCidr
        Type: CIDR
    </Field>
</Schema>

<MetaData>
    TableType: INDEXED
    TableVersion: 6241959731729006595
</MetaData>
    "Michelangelo" 32 128 "Donatello" 5.6.7.8/32
    "Raphael" 24 96 "Leonardo" 127.0.0.1/32

Add or update row by product type

This operation allows you to add or update a row in a table with a product name and contract ID. The optional Expiry data member is a time interval in seconds after which the row expires: if no expiry is given, the row does not expire. This method only applies to RTT tables.

The data in your request should contain the row to be updated or added, in either XML or JSON format (see the following examples). If your table only consists of one row, then the message body for your submit would not contain any columns, since the key field is used as the leftmost column value (see below for more on this).

The key column is matched against the leftmost column in the table. If it matches an existing row, that row is updated. Otherwise, a new row is added. Note that key is considered to be the value of the leftmost row: thus, the XML or JSON you submit in the body of your request should not contain a field for the leftmost key column: only for the subsequent columns.

In the following example the table is assumed to have two columns. The first one is updated by using the key field, and the second one is a string column whose new value will be Arizona.

<Row>
    <Columns>
        <Column>
            <Value>Arizona</Value>
            <Type>STRING</Type>
        </Column>
    </Columns>
    <Expiry>60</Expiry>
</Row>

{
    "Expiry": 60,
    "Columns": [
        {
            "Value": "Arizona",
            "Type": "STRING"
        }
    ]
}

Remove row by product type

This operation lets you delete a row from a table with a product name and contract ID. It only applies to RTT tables. The row to be deleted must have a key column (leftmost column) whose value matches key.

Data

This section provides you with the data model for the AnswerX RKS API.

Row

Encapsulates data for a row with either a call to a unique service ID or a call to a product name and contract ID.

For all REST methods (GET, PUT/POST, and DELETE), there are two ways to access your data: instance ID or product type and contract ID. See the Overview for more information.

This object may represent data with both static and RTT or dynamic tables.

Sample JSON response:

{
    "Key": "127.0.0.1",
    "Columns": [
        {
            "Value": "Utah"
        },
        {
            "Value": "127.0.0.1"
        }
    ]
}

Sample XML response:

<Row>
    <Key>127.0.0.1</Key>
    <Columns>
        <Column>
            <Value>127.0.0.1</Value>
        </Column>
        <Column>
            <Value>Utah</Value>
        </Column>
    </Columns>
</Row>

Row members

Schema

Encapsulates the schema for a table with either a call to a unique service ID or a call to a product name and contract ID. Applies in GET operations when the action is set to schema or subscribe. This object only applies to dynamic tables.

Sample JSON response:

{
    "Field": [
        {
            "Name": "HostIP",
            "Type": "CIDR"
        },
        {
            "Name": "SubscriberID",
            "Type": "STRING"
        }
    ]
}

Sample XML response:

<Schema>
    <Field>
        <Name>HostIP</Name>
        <Type>CIDR</Type>
    </Field>
    <Field>
        <Name>SubscriberID</Name>
        <Type>STRING</Type>
    </Field>
</Schema>

Schema members

Errors

If you encounter a variety of errors, the AnswerX RKS API responds with the appropriate HTTP status codes and a response object that explains them, as shown here. There are many possible causes for failure, such as malformed JSON or XML code or missing fields. Note that the error responses are in JSON format, even if the Accept header is set to XML.

JSON problems

The Akamai API platform returns HTTP Problem error objects. For example:

{
    "type": "https://problems.luna.akamaiapis.net/-/pep-authn/request-error",
    "title": "Bad request",
    "status": 400,
    "detail": "Authorization header missing",
    "instance": "https://akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx.luna.akamaiapis.net/recursive-dns-db/v1/locations",
    "method": "GET",
    "serverIp": "NNN.NNN.NNN.NNN",
    "clientIp": "NNN.NNN.NNN.NNN",
    "requestId": "xxxxxxxx",
    "requestTime": "2015-04-16T14:56:52Z"
}

In most cases, the type and title provide enough information to understand the nature of the error.

Please be sure to reference the problem type when communicating with Akamai representatives or the Akamai Developer Community.

Error responses

This API produces the following set of HTTP status codes for both success and failure scenarios:

Last modified: 12/12/2016