Manage Edge DNS as Code: DNS API

November 13, 2020 · by Javier Garza ·

This blog is part of a series on the various methods available to manage DNS as code. Previously we covered my personal favorite method - Managing Edge DNS as code with GitHub actions. In this blog, I’ll walk you through managing DNS using the DNS API.

Akamai Edge DNS is a cloud-based solution that can be implemented as a primary or secondary DNS service that leverages a globally distributed network of servers to ensure the availability, performance, and security of your DNS infrastructure.Managing DNS as Code increases developer productivity and makes it easier to manage your DNS infrastructure at scale.

Methods to manage DNS as code

There are several different ways to manage Edge DNS as code:

  1. Leverage the Edge DNS API directly using the programming language of your choice
    This method is the most flexible but requires the most development work. This method is recommended for large projects that need a lot of customization.

  2. Leverage the DNS CLI package
    This method helps teams get started with automation quickly but offers fewer customization options.

  3. Use the "akamai_dns_record" and "akamai_dns_zone" resources within the Akamai Terraform provider
    Terraform is a 3rd-party tool to orchestrate infrastructure which is great if you already use it for managing other Infrastructure as code. The main drawback of using Terraform (or any other 3rd-party tool) is that you are constrained by the functionality that has been implemented within the tool and expanding that functionality may be difficult or require more work.

  4. Use CI/CD automations like the Deploy Akamai Edge DNS zone GitHub Action
    This is my favorite approach as you can use any of the previously mentioned methods and easily add automation around it, making it very flexible and efficient.

Now, let's dive into how you can manage DNS as code with the DNS API.

Get your DNS API credentials

Most command line tools that we are using on this post rely on having API credentials stored in a “dns” section with a text file called “.edgerc” located in the user’s home directory. See the Getting Started with APIs page on for more information.

You can use a command like “cat” to verify your credentials file looks like this:

$ cat ~/.edgerc


client_secret = d7BhODpkXAPCqrCvAHae/4AqCQODfUI0oqjBbrjqQPM=

host =

access_token = akab-ahsl64pyefoj23ob-f4nd2rcvpotwnffx

client_token = akab-kzcuqwrhxtdet73o-tfskx6y3r7hk7rqg

Note: Please replace the values above with valid API credentials that have access to the DNS API, as the ones shown above are non-working sample credentials for illustration purposes.

Docker Development Environment

Through this post we are going to be running terminal commands on our Akamai Docker Development Environment which you can identify with the prompt “Akamai DevOps [~] >>”

The command below describes how to define an alias called “akadev” that will start our Akamai Development Environment.

$ alias akadev="docker run --rm -it --name akamai -v $HOME/.edgerc:/root/.edgerc akamai/shell"

$ akadev

                ___    __                         _

               /   |  / /______ _____ ___  ____ _(_)

              / /| | / //_/ __ `/ __ `__ \/ __ `/ /

             / ___ |/ ,< / /_/ / / / / / / /_/ / /

            /_/  |_/_/|_|\__,_/_/ /_/ /_/\__,_/_/


=  Welcome to the Akamai Docker Image                         =


=  Project page:                                              =

=                    =


Akamai DevOps [~] >>


Managing DNS zones and DNS records is relatively easy using the Edge DNS API and the DevOps tool of your choice.

You can use Postman to explore APIs and then use a command line tool like HTTPie to create automation scripts to deploy DNS changes using the automation tool of your choice.

Adding DNS records

Now, you'll need to add a record to your DNS.

A sample workflow would be a web form where people in your company select an existing DNS domain from a drop-down list, enter the DNS record name, type and other settings and submit the form.

Another option is to create an automated workflow that programmatically creates the required DNS records as infrastructure is being provisioned using variables. One way, or the other you are most likely going to end up with a DNS record that you need to translate into JSON format.

In order to create the following record:  300     IN      CNAME

You will need to translate this into something like this:


    "name": "",

    "rdata": [



    "ttl": 300,

    "type": "CNAME"


Now, you can make an API call. In the example below, I use HTTPie (included in the Akamai Docker Development Environment) to pass the JSON file, In this example I called this file “” and it contains the code shown above.

Akamai DevOps [~] >> http --print=HhbB -A edgegrid -a dns: POST :/config-dns/v2/zones/ <


POST /config-dns/v2/zones/ HTTP/1.1

Accept: application/json, */*;q=0.5

Content-Type: application/json

User-Agent: HTTPie/2.2.0



    "name": "",

    "rdata": [



    "ttl": 300,

    "type": "CNAME"



HTTP/1.1 201 Created

Content-Type: application/json



    "name": "",

    "rdata": [



    "ttl": 300,

    "type": "CNAME"


Note: Printing request and response headers, and request and response body is a very good practice that can help tremendously debugging failures in automated scripts. Also note that some headers were removed on the above request for brevity purposes

It may take a few minutes for the DNS record to propagate through the distributed Akamai DNS platform, but you can make a very similar request (just replace the POST method with a GET, and don’t indicate a JSON body in order to verify if the record is created):

Akamai DevOps [~] >> http --print=HhbB --json -A edgegrid -a dns: GET


This API call would return a 404 status code if the DNS record does not exist, and a 200 if it exists. You can use those status codes for your automation scripts to verify if the DNS record exists.

Updating DNS Zones

If you prefer to manage several records at the same time, you can opt for maintaining the DNS zone file and just upload it to the Akamai platform using the Post Master Zone File API call. To do this, you just need to create a text file containing the DNS zone file which in our example the text below will be inside a text file called ““ 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 900 IN SOA 1601591799 900 300 604800 180 300 IN CNAME 300 IN HTTPS 0

Note: Don’t forget to increase the serial number (in red above) whenever you update an existing zone

We can now use HTTPie (or another tool like Postman) to submit the zone file:

Akamai DevOps [~] >> http --print=HhbB -A edgegrid -a dns: POST :/config-dns/v2/zones/ Content-Type:text/dns <

This should return something like this: 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 172800 IN NS 900 IN SOA 1601591799 900 300 604800 180 300 IN CNAME 300 IN HTTPS 0

HTTP/1.1 204 No Content

Cache-Control: no-cache, no-store, max-age=0, must-revalidate

Connection: keep-alive

Date: Fri, 09 Oct 2020 01:28:58 GMT

ETag: "68732b2f-d284-4aa3-a8c6-3f42971a37d0"

Expires: 0

Pragma: no-cache

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

X-IDS-SESSION-ID: 461e8221-3388-43f0-bd83-d5b1afaa7c01

X-Trace-Id: 89925f7fbcda0294

X-XSS-Protection: 1; mode=block

The 204 response code shows the zone was accepted. The value on the eTag field contains the versionId which you can use in order to get the status of that version.  

Getting the status of a DNS zone version

You can use the API endpoint Get Zone Version to get the activation status of a zone you submitted (you need to replace the domain and versionId with the ones for your use case). In our example the API call would look like this:

Akamai DevOps [~] >> http --print=b -A edgegrid -a dns: GET :/config-dns/v2/zones/

This should return something like this:


    "activationState": "ACTIVE",

    "category": "general",

    "contractId": "C-1FRYVV3",

    "lastActivationDate": "2020-10-09T01:33:54.886265Z",

    "lastModifiedBy": "api-user-devrel",

    "lastModifiedDate": "2020-10-09T01:32:50.449161Z",

    "signAndServe": false,

    "type": "PRIMARY",

    "versionId": "e12b936c-9449-49dd-8172-a9e7b57d3f89",

    "zone": ""


Note: You may see a status of “PENDING” if you make this API call right after submitting your new DNS zone file as activations take a few minutes.


In this post we saw working examples showing how you can manage your DNS domains with the Akamai Edge DNS API by adding individual records, or by updating the complete zone file. I hope you find this information useful, and remember to “share what you know, and learn what you don’t”.

You might also like

Here are great resources you can read to learn more:

About the author

JavierJavier Garza is a developer advocate at Akamai Technologies where he helps the largest companies on the internet run fast and secure apps by leveraging web performance, security, and DevOps best practices. Javier has written many articles on HTTP/2 and web performance, and is the co-author of the O’Reilly Book, Learning HTTP/2. In 2018, Javier spoke at more than 20 developer-related events around the world, including well-known conferences like Velocity, AWS Re:Invent, and PerfMatters. His life’s motto is: share what you learn, and learn what you don’t. In his free time he enjoys challenging workouts and volunteering for non-profits that support children and education.