DNS—Zone Record Management API

Welcome to Akamai’s Enhanced DNS service. Enhanced DNS is designed to integrate easily with your existing DNS infrastructure to provide a secure, high performance, highly available and scalable solution for DNS hosting. As part of this service, Akamai runs name servers in multiple networks and in many geographic locations that are capable of resolving queries for your zones. Akamai’s IP Anycast technology is also capable of providing an unprecedented level of reliability and performance for name resolution.

The Enhanced DNS service supports two types of Zones:

  • Primary: Akamai will serve the DNS records of your zones without the need for master DNS servers maintained by you.

  • Secondary: Akamai will serve the DNS records of your zones obtained by performing secured zone transfers from your master name server.

This API focuses on primary zones, specifically the management of DNS records of an existing primary zone.

Record Management

Once a primary Enhanced DNS zone is provisioned in Akamai Luna Control Center, a nonbrowser-based client may invoke this API to manage the DNS records of the Zone. To update a zone configuration,

  1. Retrieve the current zone configuration (GET /config-dns/v1/zones/{zone}).

  2. Increment the SOA record’s serial field.

  3. Add new records, remove old ones and update existing records in the Zone configuration as needed.

  4. Submit the full zone configuration (POST /config-dns/v1/zones/{zone}).

Example: Modifying an Existing Zone Record Set Configuration

Consider the most basic Zone configuration for example.com: a Zone with a single SOA record and two NS records:

example.com.            900     IN      SOA     use4.akamai.com. hostmaster.akamai.com. 1271354824 900 300 604800 180
example.com.            3600    IN      NS      use4.akam.net.
example.com.            3600    IN      NS      use3.akam.net.

Our task will be to add a new A Record with the name www, and an IP address 1.2.3.4:

GET /config-dns/v1/zones/example.com
{
    "token": "a184671d5307a388180fbf7f11dbdf46",
    "zone": {
        "name": "example.com",
        "soa": {
            "contact": "hostmaster.akamai.com.",
            "expire": 604800,
            "minimum": 180,
            "originserver": "use4.akamai.com.",
            "refresh": 900,
            "retry": 300,
            "serial": 1271354824,
            "ttl": 900
        },
        "ns": [
            {
                "active": true,
                "name": "",
                "target": "use4.akam.net.",
                "ttl": 3600
            },
            {
                "active": true,
                "name": "",
                "target": "use3.akam.net.",
                "ttl": 3600
            }
        ]
    }
}

Note the token field. It is a unique value calculated for every zone configuration, and must be presented with the Zone submission, which is used by Luna to guarantee that the submission modifies the current configuration. This is to prevent inadvertently overwriting another client’s submission.

POST /config-dns/v1/zones/example.com
{
    "token": "a184671d5307a388180fbf7f11dbdf46",
    "zone": {
        "name": "example.com",
        "soa": {
            "contact": "hostmaster.akamai.com.",
            "expire": 604800,
            "minimum": 180,
            "originserver": "use4.akamai.com.",
            "refresh": 900,
            "retry": 300,
            "serial": 1271354825,
            "ttl": 900
        },
        "ns": [
            {
                "active": true,
                "name": "",
                "target": "use4.akam.net.",
                "ttl": 3600
            },
            {
                "active": true,
                "name": "",
                "target": "use3.akam.net.",
                "ttl": 3600
            }
        ],
        "a": [
            {
                "active": true,
                "name": "www",
                "target": "1.2.3.4",
                "ttl": 3600
            }
        ]
    }
}

Example: Creating a New Zone Record Set Configuration

If a Zone has been created in Luna Control Center, but hasn’t had any records added yet, attempts to retrieve the Zone will result in a 404 return code, as the Zone’s configuration does not exist yet.

To create, the POST request will look the same as modifying an existing Zone, with one exception: the token value must be set to new:

POST /config-dns/v1/zones/example.com
{
    "token": "new",
    "zone": {
        "name": "example.com",
        "soa": {
            "contact": "hostmaster.akamai.com.",
            "expire": 604800,
            "minimum": 180,
            "originserver": "use4.akamai.com.",
            "refresh": 900,
            "retry": 300,
            "serial": 1271354825,
            "ttl": 900
        },
        "ns": [
            {
                "active": true,
                "name": "",
                "target": "use4.akam.net.",
                "ttl": 3600
            },
            {
                "active": true,
                "name": "",
                "target": "use3.akam.net.",
                "ttl": 3600
            }
        ],
        "a": [
            {
                "active": true,
                "name": "www",
                "target": "1.2.3.4",
                "ttl": 3600
            }
        ]
    }
}

Last modified: 12/12/2016