The Traffic Management API

The Internet domain name system (DNS) is a distributed system that allows computer programs to issue queries about domain names, to which the DNS returns one or more answers. The most common use for DNS is to convert hostnames, such as www.customer.com, into IP addresses, which identify a particular computer at a particular Internet location.

In the most traditional usage, a query’s answers are static. Someone types them into a configuration file, and they change only when the file changes.

A dynamic DNS system returns answers that are computed on the fly, and can vary from one query to the next. A typical usage would return the IP address of a server assigned dynamically via DHCP, an address that would occasionally change, as is common with most home Internet connections.

Akamai’s GTM system is a dynamic DNS system. It manages traffic to your data centers by choosing the best answers, from one moment to the next, to return client nameservers in response to their queries about GTM domains.

Getting Started

The basic building block of a Traffic Management configuration is a Domain. DNS forms a tree-structured namespace. In the following list of domain names, each item is a domain:

  • com
  • customer.com
  • sales.customer.com

Each domain is also a subdomain of the one above it in the list. In Akamai’s GTM system, the term domain is used in a slightly restricted sense. A GTM domain is a DNS domain, whose name usually ends in .akadns.net. Several important attributes are specified at the GTM domain level, including Luna access control. Anyone with permission to edit a GTM domain has permission to modify or delete any of the properties (subdomains) within that domain.

This overview walks you through setting up a new domain, example.akadns.net. Run the Create or Update a Domain operation:

PUT /config-gtm/v1/domains/example.akadns.net HTTP/1.1
Accept: application/json
Content-type: application/json
Content-Length: 173

{
    "name": "example.akadns.net",
    "type": "weighted",
    "emailNotificationList": ["our.admin@example.com"],
    "modificationComments": "New Traffic Management domain."
}

This operation creates a weighted domain named example.akadns.net. It also specifies that our.admin@example.com is sent an email for each change the Traffic Management system processes, as well as other notifications such as propagation progress, validation, or error messages. The system confirms the domain creation with a 201 status code, and returns a full representation of the new domain:

HTTP/1.1 201 Created
Date: Mon, 04 Aug 2014 15:30:39 GMT
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

{
    "resource": {
        "cidrMaps": [],
        "datacenters": [],
        "defaultErrorPenalty": 75,
        "defaultSslClientCertificate": null,
        "defaultSslClientPrivateKey": null,
        "defaultTimeoutPenalty": 25,
        "emailNotificationList": [ "our.admin@example.com" ],
        "geographicMaps": [],
        "lastModified": "2014-08-04T15:30:40.057+0000",
        "lastModifiedBy": "admin",
        "loadFeedback": false,
        "loadImbalancePercentage": null,
        "modificationComments": "New Traffic Management domain.",
        "name": "example.akadns.net",
        "properties": [],
        "resources": [],
        "status": {
            "changeId": "abb94136-dd94-4779-bfb0-fcfac67fb843",
            "message": "Change Pending",
            "passingValidation": true,
            "propagationStatus": "PENDING",
            "propagationStatusDate": "2014-08-04T15:30:40.057+0000"
        },
        "type": "weighted"
    },
    "status": {
        "changeId": "abb94136-dd94-4779-bfb0-fcfac67fb843",
        "message": "Change Pending",
        "passingValidation": true,
        "propagationStatus": "PENDING",
        "propagationStatusDate": "2014-08-04T15:30:40.057+0000"
    }
}

Notice that the API server fills in many fields such as defaultErrorPenalty and defaultTimeoutPenalty with default values.

Your set of available domain types is determined by your contract. The domain’s type also places a restriction on what type of property you can create under the domain. The following lists each domain type, along with the property types you can associate with them:

  failover-only static weighted basic full
failover
qtr
geographic
cidrmapping
asmapping
weighted-round-robin
weighted-hashed
weighted-round-robin-with-load-feedback
performance

While the new domain is a good start, it’s still incomplete. It needs at least two Datacenters defined, and at least one Property before it’s ready for use. This Create a Data Center operation creates two data centers for the domain, starting with a Winterfell data center:

POST /config-gtm/v1/domains/example.akadns.net/datacenters HTTP/1.1
Accept: application/json
Content-type: application/json
Content-Length: 145

{
    "city": "Downpatrick",
    "continent": "EU",
    "country": "GB",
    "latitude": 54.367,
    "longitude": -5.582,
    "nickname": "Winterfell"
}

The API assigns a datacenterId, which appears as a member in the data center’s JSON response, and helps form the Location header, which you can navigate to access the new data center:

HTTP/1.1 201 Created
Date: Mon, 04 Aug 2014 15:49:08 GMT
Location: /config-gtm/v1/domains/example.akadns.net/datacenters/3131
Transfer-Encoding: chunked
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

{
    "resource": {
        "city": "Downpatrick",
        "cloneOf": null,
        "continent": "EU",
        "country": "GB",
        "datacenterId": 3131,
        "defaultLoadObject": null,
        "latitude": 54.367,
        "longitude": -5.582,
        "nickname": "Winterfell",
        "stateOrProvince": null,
        "virtual": true
    },
    "status": {
        "changeId": "0a580f0a-d585-4fc0-a3ff-47c79e8fd7fc",
        "message": "Change Pending",
        "passingValidation": true,
        "propagationStatus": "PENDING",
        "propagationStatusDate": "2014-08-04T15:49:10.111+0000"
    }
}

The datacenterId is important, as it’s referenced by many other entities across the domain. Now run the operation again to add the second data center:

POST /config-gtm/v1/domains/example.akadns.net/datacenters HTTP/1.1
Accept: application/json
Content-type: application/json
Content-Length: 248

{
    "city": "Snæfellsjökull",
    "continent": "EU",
    "country": "IS",
    "latitude": 64.808,
    "longitude": -23.776,
    "nickname": "Frostfangs"
}

That data center is assigned a datacenterId of 3131, which now provides the minimum for a valid domain:

GET /config-gtm/v1/domains/example.akadns.net/datacenters
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

{
    "items": [
        {
            "city": "Downpatrick",
            "cloneOf": null,
            "continent": "EU",
            "country": "GB",
            "datacenterId": 3131,
            "defaultLoadObject": {
                "loadObject": null,
                "loadObjectPort": 0,
                "loadServers": null
            },
            "latitude": 54.367,
            "longitude": -5.582,
            "nickname": "Winterfell",
            "stateOrProvince": null,
            "virtual": true
        },
        {
            "city": "Snæfellsjökull",
            "cloneOf": null,
            "continent": "EU",
            "country": "IS",
            "datacenterId": 3132,
            "defaultLoadObject": {
                "loadObject": null,
                "loadObjectPort": 0,
                "loadServers": null
            },
            "latitude": 64.808,
            "longitude": -23.776,
            "nickname": "Frostfangs",
            "stateOrProvince": null,
            "virtual": true
        }
    ]
}

The last piece you need is a Property, or subdomain, of the example.akadns.net domain. This Create or Update a Property operation creates a property named origin, as a weighted round-robin load balanced property with a 50/50 split:

PUT /config-gtm/v1/domains/example.akadns.net/properties/origin HTTP/1.1
Content-type: application/json
Accept: application/json
Content-Length: 534

{
    "name": "origin",
    "handoutMode": "normal",
    "failoverDelay" : 0,
    "failbackDelay" : 0,
    "trafficTargets": [
        {
            "datacenterId": 3131,
            "enabled": true,
            "servers": [ "1.2.3.5" ],
            "weight": 50.0
        },
        {
            "datacenterId": 3132,
            "enabled": true,
            "servers": [ "1.2.3.4" ],
            "weight": 50.0
        }
    ],
    "type": "weighted-round-robin",
    "scoreAggregationType": "mean"
}

This basic setup splits requests evenly between the Winterfell and Frostfangs data center, whose datacenterId values are 3131 and 3132. One thing you may want to change is for Traffic Management only to provide IPs that are alive. Run the operation again to specify a set of livenessTests:

PUT /config-gtm/v1/domains/example.akadns.net/properties/origin HTTP/1.1
Host: iamakamai.qaextranet.akamai.com
Content-type: application/json
Accept: application/json
Content-Length: 982

{
    "name": "origin",
    "handoutMode": "normal",
    "failoverDelay" : 0,
    "failbackDelay" : 0,
    "trafficTargets": [
        {
            "datacenterId": 3131,
            "enabled": true,
            "servers": [ "1.2.3.5" ],
            "weight": 50.0
        },
        {
            "datacenterId": 3132,
            "enabled": true,
            "servers": [ "1.2.3.4" ],
            "weight": 50.0
        }
    ],
    "type": "weighted-round-robin",
    "scoreAggregationType": "mean",
    "livenessTests": [
        {
            "disableNonstandardPortWarning": false,
            "hostHeader": "foo.example.com",
            "httpError3xx": true,
            "httpError4xx": true,
            "httpError5xx": true,
            "name": "health-check",
            "testInterval": 60,
            "testObject": "/status",
            "testObjectPort": 80,
            "testObjectProtocol": "HTTP",
            "testTimeout": 25.0
        }
    ]
}

With this configuration, server monitors assigned to your domain test each IP address every 60 seconds (the testInterval) by running the equivalent of this command:

curl -H "Host: foo.example.com" http://1.2.3.5/status

The server monitor treats status codes in the 300, 400, and 500 range as errors, controlled by the httpError3xx, httpError4xx, httpError3xx members, respectively; Test agents also time out tests after 25 seconds (the testTimeout).

API Versioning

In the examples above, the response’s media type is application/vnd.config-gtm.v1.0+json. The API currently supports five media types:

  • application/json
  • application/vnd.config-gtm.v1.0+json
  • application/vnd.config-gtm.v1.1+json
  • application/vnd.config-gtm.v1.2+json
  • application/vnd.config-gtm.v1.3+json

The application/json type is synonymous with the earliest application/vnd.config-gtm.v1.0+json version, regardless of how many other versions are incrementally added over time as the service evolves. API clients may choose to adopt the new resource versions, or stay on the initial v1.0 version until the need arises to upgrade. Clients should specify the exact version of the representation, for example:

Accept: application/vnd.config-gtm.v1.0+json

Contracts and Groups

When you create a new domain, you need to associate it with a contract and a group, important information when deploying various Akamai features:

  • Groups: Each account features a hierarchy of groups, which control access to domains and help consolidate reporting functions, typically mapping to an organizational hierarchy. Using either the Luna portal or the User Administration API, account administrators can assign domains to specific groups, each with its own set of users and accompanying roles. Your access to any given domain depends on the role set for you in its group. Along with information about the contract, you may need the group identifier to create a new domain.

  • Contracts: Each account features one or more contract, each of which has a fixed term of service during which specified Akamai products and modules are active. Along with information about the group, you may need the contract identifier to create a new domain.

Running the Create or Update a Domain operation may require you to provide a contractId or gid (group ID), under the following circumstances:

Client has access to… Required parameters…
One contract and group. Neither parameter is required. The API can derive the data automatically.
One contract, and more than one group. Requires the gid parameter. The API needs to know the group in which to create the domain. It derives the contract automatically.
More than one contract, and one group. Requires the contractId parameter. The API needs to know the contract under which to create the domain. It derives the group automatically.
More than one contract and group. Both contractId and gid parameters are required, since the API needs to know the contract and group under which to create the domain.

If you need to provide identifiers, but you don’t know what they are, run the List Contracts or List Groups operations.

NOTE: The Identity Management Application allows you to limit the groups a client has access to. If you are able to limit access to a single group, one linked with only one contract, then the client doesn’t the group or contract IDs when creating domains.

API Hypermedia

The API’s data objects feature embedded link relations that provide URL paths that allow direct navigation to each object. For example, items within a list of domains feature link relations such as the following, where the href responds to a GET request, and a rel of self indicates that it identifies the unique object.

"links": [
    {
        "href": "/config-gtm/v1/domains/example.akadns.net",
        "rel": "self"
    }
],

Last modified: 1/22/2018