Traffic Management API

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 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:

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:

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:

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:

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.

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.