Traffic Management API Data

This section provides details on all the JSON object types the Traffic Management API exchanges, and their accompanying schemas.

JSON Schemas

Version 1.0, application/json, application/vnd.config-gtm.v1.0+json:

Object Type JSON Schema
Datacenter datacenter-vnd.config-gtm.v1.0.schema.json
Property property-vnd.config-gtm.v1.0.schema.json
Resource resource-vnd.config-gtm.v1.0.schema.json
Geographic Map geographic-map-vnd.config-gtm.v1.0.schema.json
CIDR Map cidr-map-vnd.config-gtm.v1.0.schema.json
Domain domain-vnd.config-gtm.v1.0.schema.json

Version 1.1, application/vnd.config-gtm.v1.1+json:

Object Type JSON Schema
Datacenter datacenter-vnd.config-gtm.v1.1.schema.json
Property property-vnd.config-gtm.v1.1.schema.json
Resource resource-vnd.config-gtm.v1.1.schema.json
Geographic Map geographic-map-vnd.config-gtm.v1.1.schema.json
CIDR Map cidr-map-vnd.config-gtm.v1.1.schema.json
Autonomous System Map as-map-vnd.config-gtm.v1.1.schema.json
Domain domain-vnd.config-gtm.v1.1.schema.json

Version 1.2, application/vnd.config-gtm.v1.2+json:

Object Type JSON Schema
Datacenter datacenter-vnd.config-gtm.v1.2.schema.json
Property property-vnd.config-gtm.v1.2.schema.json
Resource resource-vnd.config-gtm.v1.2.schema.json
Geographic Map geographic-map-vnd.config-gtm.v1.2.schema.json
CIDR Map cidr-map-vnd.config-gtm.v1.2.schema.json
Autonomous System Map as-map-vnd.config-gtm.v1.2.schema.json
Domain domain-vnd.config-gtm.v1.2.schema.json

Version 1.3, application/vnd.config-gtm.v1.3+json:

Object Type JSON Schema
Datacenter datacenter-vnd.config-gtm.v1.3.schema.json
Property property-vnd.config-gtm.v1.3.schema.json
Resource resource-vnd.config-gtm.v1.3.schema.json
Geographic Map geographic-map-vnd.config-gtm.v1.3.schema.json
CIDR Map cidr-map-vnd.config-gtm.v1.3.schema.json
Autonomous System Map as-map-vnd.config-gtm.v1.3.schema.json
Domain domain-vnd.config-gtm.v1.3.schema.json

Datacenter

A data center or a region, is a group of servers that is a unit of load partitioning. Traffic Management balances load across data centers but not within data centers. Each property can be served from multiple customer data centers. For example, www might be in DC1 (SantaClara), DC2 (London) and DC3 (Tokyo), and foo in DC1 and DC3.

JSON schema: datacenter-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
datacenterId Number Integer identifier to new data centers.
Optional
city String Name of the city where data center is located.
cloneOf Number Integer identifying a clone of a physical or virtual data center used to sub-divide the collection of servers. This property tracks the datacenterId of the data center this data center is designated a clone of, if any.
continent Enumeration Two-letter continent code, either AF, AS, EU, NA, OC, OT, or SA, representing the continent where the data center is located. If omitted, Traffic Management fills it in based on looking up the country code in a country-to-continent mapping published by Akamai’s EdgeScape service.
country String Two-letter ISO 3166 country code of the country where data center is located.
defaultLoadObject DefaultLoadObject
latitude Number Latitude of the city where data center is located.
longitude Number Longitude of the city where data center is located.
nickname String Nickname for this data center, maximum 256 characters.
stateOrProvince String Name of the state or province where data center is located.
virtual Boolean A read-only, documentation-oriented field to convey to clients whether or not the data center is virtual or physical, the latter meaning the datacenter has an Akamai Network Agent installed, and its physical location (latitude, longitude, etc.) is fixed.

DefaultLoadObject

The load reporting interface between the customer and the Global Traffic Management system. A load object is a file that provides real-time information about the current, maximum allowable, and target load on each resource.

This default load object is intended to be shared. Individual Resources can specify useDefault to use it instead of specifying their own.

Member Type Description
Required
loadObject String Load object that Traffic Management requests. A load object is a file that provides real-time information about the current, maximum allowable, and target load on each resource. String may not begin with a : character, and has a maximum of 256 characters.
loadObjectPort Number TCP port with which to connect when requesting the load object. A value of 0 means to use the default port, equivalent to either 80 or 443.
loadServers Array List of servers from which to request the load object. Must contain IPv4 or IPv6 addresses, or DNS names that contain A or AAAA records. If a DNS name has both A and AAAA records, then Traffic Management picks one randomly. For IP addresses, do not use non-routable RFC–1918 addresses.

Property

Representation of Traffic Management property, (e.g., www) which in DNS terms is a subdomain of the domain. Combined with its domain (e.g., example.akadns.net), the fully qualified domain name www.example.akadns.net is used for load balancing.

JSON schema: property-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
handoutMode Enumeration Relevant only when you have more than one server IP in a data center, this specifies behavior of how IPs are returned when more than one is alive and available. Either normal, persistent, one-ip, one-ip-hashed, or all-live-ips, defaulting to normal.
name String A property is a subdomain within a Traffic Management domain; the property name is combined with the domain name, and is used for load balancing. The property’s name plus the domain name should not be longer than 255 characters. It may not begin or end with a dot (.), may not begin resource, or ax followed by a set of digits. It must match this pattern: ^[\w-]+(\.[\w-]+)*$
scoreAggregationType Enumeration Specifies how Traffic Management aggregates liveness test scores across different tests, when multiple tests are configured. Either mean, median, best, or worst, the default value.
trafficTargets TrafficTarget The traffic target is an option for where to direct traffic. Lists of traffic targets include only those that are available with the activity the customers are performing.
type Enumeration Specifies the type of load balancing behavior for this property, either failover, geographic, cidrmapping, weighted-round-robin, weighted-hashed, weighted-round-robin-load-feedback, qtr, or performance. An additional value of asmapping requires the application/vnd.config-gtm.v1.1+json media type. See API Versioning for more information.
Optional
backupCName String If Traffic Management decides that all of the servers configured for your property are down, and you have configured a backup CNAME, then queries for the property return this backup CNAME. If this field is set, backupIp must not be set, and vise versa.
backupIp String Backup IP to hand out when all targets are declared down. The IP type coincides with property’s IPv6 setting. If this field is set, the backupCName field must not be set, and vise versa.
balanceByDownloadScore Boolean Enables download score based load balancing. Traffic Management estimates the load on your datacenters based on how long they take to respond to liveness tests.
cname String The fully qualified name in your domain that is aliased to a particular property; the public name of the property.
comments String Maximum of 1,000 characters.
dynamicTTL Number The TTL (in integer seconds) for records that might change from moment to moment based on liveness and load balancing: A and AAAA records, and CNAMEs. Value ranges from 30 to 3600, defaulting to 300.
failbackDelay Number Failback delay in integer seconds, minimum 0. If specified, when a server has been down, and comes back up (its liveness test starts succeeding again), then Traffic Management won’t consider it up right away, but only after the failback delay has elapsed and tests continue to succeed.
failoverDelay Number Failover delay in seconds, minimum 0. If specified, when a server begins failing its liveness test, Traffic Management doesn’t consider it down right away, but only after the failover delay has elapsed and the errors persist.
handoutLimit Number Handout Limit limits the number of live IPs handed out to a DNS request. This setting will only apply if the handoutMode setting for the property is either normal or persistent. The default value is 8 if this field is unset (null).

Note: Requires application/vnd.config-gtm.v1.3+json to enable.
healthMax Number If a backup CNAMEs are provided for a property, then it is reasonable for all IPs to be declared unhealthy. healthMax defines the absolute limit beyond which IPs are called unhealthy. The value is multiplied by the smaller of the timeout penalty and the error penalty, and any server with a score greater than this product is declared down.
healthMultiplier Number Configures a cutoff value that is computed from the median scores; any server with a score over the cutoff value are considered dead, and load won’t be sent to it. The cutoff is computed from the minimum score across all data centers (for a given property) and two parameters: health_multiplier and health_threshold. The cutoff is either health_multiplier (default value: 1.5) times the minimum score, or the health_threshold (default value: 4), whichever is greater. For more information, see How GTM Determines Server Liveness in the Understanding and Using Global Traffic Management guide.
healthThreshold Number Configures a cutoff value that is computed from the median scores; any server with a score over the cutoff value are considered dead, and load won’t be sent to it. The cutoff is computed from the minimum score across all data centers (for a given property) and two parameters: health_multiplier and health_threshold. The cutoff is either health_multiplier (default value: 1.5) times the minimum score, or the health_threshold (default value: 4), whichever is greater. For more information, see How GTM Determines Server Liveness in the Understanding and Using Global Traffic Management guide.
ipv6 Boolean Specifies the type of IP address handed out by this property. A true value indicates that all IP addresses specified are IPv6, and all hostnames must resolve to an AAAA records. A false value indicates IPv4 addresses, with whose hostnames must resolve to A records. Requires access to IPv6 feature to enable.
lastModified String A date-time string.
livenessTests LivenessTest Liveness tests that are to be run periodically to determine whether your servers are alive.
loadImbalancePercentage Number The load imbalance percentage controls how imbalanced Traffic Management allows the load to be, the percentage by which the demand sent to a data center is permitted to exceed the configured value. Allowed range is 0 to 1000000.
mapName String Name of GeographicMap or CIDRMap to use if property type is either geographic or cidrmapping, in which case the member is required. Must reference an existing Geographic Map in the same domain if the type is geographic, or CIDR Map if the type is cidrmapping.
maxUnreachablePenalty Number Minimum of 0.
mxRecords MXRecord Configures MX Records to be handed out to MX record type queries. Note that no mapping nor liveness testing is done; the same MX records are handed out for every request.
staticTTL Number specifies the the TTL (in integer seconds from 30 to 3600) for record types that do not change moment-to-moment (MX, SPF and TXT records). These change only when the user makes a change to the configuration. Required if mxRecords are present.
stickinessBonusConstant Number Integer from 0 to 30000. The stickiness constant is one of two settings for configuring data center affinity; the other is stickinessBonusPercentage. The constant specifies that a user should not be switched unless the resulting improvement to their score exceeds a configured threshold. Correctly configured, this keeps small variations in scores from flipping users from one data center to the next, but allows users to be moved when the score difference is so great that their performance would otherwise suffer. This setting configures stickiness as an absolute score for a data center. It only applies if property’s type is performance and its domain type is full.
stickinessBonusPercentage Number Integer from 0 to 100. The stickiness bonus is one of two settings for configuring data center affinity; the other is stickinessBonusConstant. The bonus specifies that a user should not be switched unless the resulting improvement to their score exceeds a configured threshold. Correctly configured, this keeps small variations in scores from flipping users from one data center to the next, but allows users to be moved when the score difference is so great that their performance would otherwise suffer. This setting configures stickiness as a percentage of the score for a data center. It only applies if the property’s type is performance and the domain type is full.
unreachableThreshold Number Decimal between 0 and 1. For performance domains, a penalty is added to liveness test scores from datacenters that have an aggregate loss fraction higher than unreachable threshold. A value of 1.0 (or null, the default) disables any unreachability penalty.
useComputedTargets Boolean Specifies that you want Traffic Management to automatically compute target load, meaning that only the current load is being reported by your load objects (either by omission, or by using non-xml load objects). For more information, see Computed Targets in the Understanding and Using Global Traffic Management guide. Only valid for load-feedback domains.

TrafficTarget

The traffic target is an option for where to direct traffic. Lists of traffic targets include only those that are available with the activity the customers are performing.

  • For geographic mapped properties, it is always a CNAME.

  • For Mirror Failover, it can be any set of servers.

  • For load balanced properties, this is a set of servers that are all within the same data center. Customers can have multiple traffic targets associated with the same data center (sub-data centers).

Member Type Description
Required
datacenterId Number Integer identifier for an existing data center in the domain.
enabled Boolean
Optional
handoutCName String Maximum 63 characters for the labels, 255 characters overall. May contain alphanumeric, hyphens, and underscores, but not literal IPv4 addresses. No leading or trailing hyphens are allowed.
name String Nickname for this Traffic Target.
servers Array
weight Number Required when the enclosing property’s type is failover, weighted, weighted-with-load-feedback, or performance. For failover properties, set this value to 1 for the Traffic Target you want to mark as primary. For weighted, weighted-with-load-feedback or performance, set this to the percentage of the total load. The sum of this value, for all enabled targets, must add up to 100.

LivenessTest

You can optionally configure Traffic Management to perform liveness tests periodically to determine whether your servers are alive. When you do this, Traffic Management tries to return answers that contain only the A records for live servers. The liveness tests are performed by Akamai systems out in the Internet called web agents. Each of your datacenters is liveness-tested by several agents, chosen for proximity to your data center (closer is better) and for network diversity (you don’t want all the tests conducted from the same ISP, otherwise a local problem in that ISP would falsely declare your data center down).

If all servers for a property are failing their liveness tests, GTM considers them all up, as it has no basis for preferring any of them.

A data center is considered up if any of the servers in it are considered up.

Member Type Description
Required
name String Maximum 128 characters.
testInterval Number Interval at which test is run, in integer seconds, minimum of 10.
Optional
answersRequired Boolean If testObjectProtocol is DNS, requires an answer to the DNS query to be considered a success.

Note: Requires application/vnd.config-gtm.v1.3+json to enable.
disableNonstandardPortWarning Boolean Disables warnings when using non-standard ports. For instance, Traffic Management does not emit a warning for specifying port 1234 when the testObjectProtocol is http, as HTTP typically uses port 80.
hostHeader String Sent if the testObjectProtocol is http or https
httpError3xx Boolean Treats a 3xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp
httpError4xx Boolean Treats a 4xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp
httpError5xx Boolean Treats a 5xx HTTP response as a failure if the testObjectProtocol is http, https, or ftp
peerCertificateVerification Boolean Validate origin certificate. Applies to tests with testObjectProtocol = https.

Note: Requires application/vnd.config-gtm.v1.3+json to enable.
recursionRequested Boolean If testObjectProtocol is DNS, DNS query will be recursive.

Note: Requires application/vnd.config-gtm.v1.3+json to enable.
requestString String Required if testObjectProtocol is tcp or tcps. Maximum 512 characters.
resourceType Enumeration If testObjectProtocol is DNS, specifies query type. Values must be one of : A, AAAA, AFSDB, CNAME, HINFO, LOC, MX, NAPTR, NS, PTR, RP, SOA, SPF, SRV, SSHFP, TXT, DNSKEY, DS, NSEC3, NSEC3PARAM, RRSIG. Additional support for unknown types (TYPENNNNN) where NNNNN is an integer from 1 through 65535.

Note: Requires application/vnd.config-gtm.v1.3+json to enable.
responseString String
sslClientCertificate String Base64-encoded certificate.
sslClientPrivateKey String Base64-encoded private key. Private keys are often protected with a passphrase, but Traffic Management has no mechanism for supplying a passphrase, so the private key used must not have a passphrase. The private key used to generate a certificate (or the CSR used to request the certificate) for this purpose must be a throwaway one not used for any other purpose.
testObjectPassword String Required if testObjectProtocol is ftp. Maximum 128 characters.
testObjectPort Number Integer ranging from 0 to 65535.
testObjectProtocol Enumeration Either HTTP, HTTPS, DNS, FTP, POP, POPS, SMTP, SMTPS, TCP, or TCPS.

Note: DNS requires application/vnd.config-gtm.v1.3+json to enable.
testObjectUsername String Required if testObjectProtocol is ftp. Maximum 256 characters.
testObject String Required if testObjectProtocol is http or https. Maximum 256 characters. The format /^:[\d]+/.*$/ is deprecated; use the port value instead.
testTimeout Number Range from 0.001 to 60 seconds.

MXRecord

Member Type Description
Required
exchange String A valid domain name to handout for MX queries.
priority String Priority value set in rdata of DNS response for this host.

Resource

An abstract entity that governs the properties within a data center and has the ability to constrain the load on the properties that it governs. Consider a resource as something that can impose a capacity constraint on the load associated with one or more properties in a data center. The goal of resources is to encapsulate the architecture and topology of the network in a data center.

For example, each property normally has an associated resource that represents the capacity of the servers for that property. In addition, there might be a resource that constrains the aggregate bandwidth available to all properties in a data center.

JSON schema: resource-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
name String Maximum 150 characters, with no spaces.
Optional
aggregationType Enumeration Either sum, median, or latest.
constrainedProperty String Must be either the name of an existing property in the domain, the literal string ** for all properties in the domain, or null for no properties.
decayRate Number Decimal between 0 and 1.
description String Maximum 256 characters.
hostHeader String Valid DNS hostname, maximum 255 characters.
leaderString String Maximum 256 characters.
leastSquaresDecay Number Decimal between 0 and 1.
loadImbalancePercentage Number Range of 0 to 1000000.
maxUMultiplicativeIncrement Number Minimum of 1.
resourceInstances ResourceInstance
type Enumeration Either XML load object via HTTP, XML load object via HTTPS, Non-XML load object via HTTP, Non-XML load object via HTTPS, or Download score.
upperBound Number

ResourceInstance

Member Type Description
Required
datacenterId Number Integer identifier for an existing data center in the domain.
loadObject String Maximum 256 characters, not starting with a colon (:).
Optional
loadObjectPort Number TCP port, an integer from 0 to 65535. A port of 0 means the default port, either 80 or 443.
loadServers Array Values must be a IPv4 or IPv6 address, or DNS name containing an A or AAAA record. If the DNS name has both A and AAAA records, GTM picks one randomly. IP addresses must not be non-routable RFC–1918 addresses.

GeographicMap

Geographic mapping allows you to configure a property that returns a CNAME based on the requester’s country. You can reuse maps for multiple properties or create new ones. The minimum number of definitions per-map is two so that:

  1. At least one maps one or more countries to a data center;
  2. One routes all other traffic.

JSON schema: geographic-map-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
assignments GeographicAssignment
defaultDatacenter GeographicDefaultDatacenter
name String From 1 to 128 non-space characters.

GeographicAssignment

Member Type Description
Required
countries Array Array of country codes.
datacenterId Number Unique integer identifier for an existing data center in the domain.
nickname String From 1 to 128 non-space characters.

GeographicDefaultDatacenter

Member Type Description
Required
datacenterId Number Integer identifier each property must use for the All Others CNAME. A value of 5400 is strongly recommended.
Optional
nickname String Maximum 256 characters. If blank, the value defaults to Default Mapping.

CIDRMap

CIDR mapping allows you to configure a property that returns a CNAME based on the requester’s nameserver’s source (v4) IP address. You can reuse maps for multiple properties or create new ones. The minimum number of definitions per-map is two so that:

  1. At least one maps one or more CIDR blocks to a data center.
  2. One routes all other traffic.

JSON schema: cidr-map-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
assignments CIDRAssignment
defaultDatacenter CIDRDefaultDatacenter
name String Requires 1 to 255 non-space characters.

CIDRAssignment

Member Type Description
Required
blocks String Each entry represents a CIDR block to match on.
datacenterId Number Integer identifier for an existing data center in the domain.
nickname String Range of 1–128 non-space characters.

CIDRDefaultDatacenter

Member Type Description
Required
datacenterId Number Integer identifier each property must use for the All Others CNAME. A value of 5400 is strongly recommended.
nickname String Maximum 256 characters. If omitted, defaults to All Other CIDR Blocks.

AutonomousSystemMap

Autonomous System (AS) mapping allows you to configure a property that returns a CNAME based on what Autonomous System the requester’s nameserver’s IP Address belongs to. You can reuse maps for multiple properties or create new ones. The minimum number of definitions per-map is two so that:

  1. At least one maps one or more AS Numbers to a data center;
  2. One routes all other traffic.

JSON schema: as-map-vnd.config-gtm.v1.1.schema.json

NOTE: AS Maps require the application/vnd.config-gtm.v1.1+json Media Type. See API Versioning for more information.

Member Type Description
Required
assignments ASAssignment
defaultDatacenter ASDefaultDatacenter
name String Range of 1–128 non-space characters.

AutonomousSystemAssignment

Member Type Description
Required
asNumbers Number Integer from 1 to 4294967295.
datacenterId Number Unique integer identifier for an existing data center in the domain.
nickname String Range of 1 to 128 non-space characters.

AutonomousSystemDefaultDatacenter

Member Type Description
Required
datacenterId Number Integer identifier each property must use for the All Others CNAME. A value of 5400 is strongly recommended.
Optional
nickname String Maximum 256 characters. Defaults to Default Mapping.

Domain

A Traffic Management domain is a domain with one or more subdomains that share a number of attributes that can only be configured domain-wide. These attributes include use of load feedback, load imbalance factor, the set of available data centers, etc. Each Domain object is a representation of a complete Traffic Management domain (e.g., example.akadns.net)

JSON schema: domain-vnd.config-gtm.v1.0.schema.json

Member Type Description
Required
cidrMaps CIDRMap
datacenters Datacenter
defaultErrorPenalty Number Integer, defaulting to 75.
defaultSslClientCertificate String Base64-encoded certificate If this value is specified, it applies to all liveness tests in the Domain, unless they have their own certificate and key specified. If that’s not what a user wants, they should leave this field blank and set the key/cert on a per-liveness test basis.
defaultSslClientPrivateKey String Base64-encoded private key Private keys are often protected with a passphrase, but Traffic Management has no mechanism for supplying a passphrase, so the private key used must not have a passphrase. The private key used to generate a certificate (or the CSR used to request the certificate) for this purpose must be a throwaway one not used for any other purpose. If this value is specified, it applies to all liveness tests in the Domain, unless they have their own certificate and key specified. If that’s not what a user wants, they should leave this field blank and set the key/cert on a per-liveness test basis.
defaultTimeoutPenalty Number Integer, defaulting to 25.
emailNotificationList Array Lists valid email address.
geographicMaps GeographicMap
lastModifiedBy String Read-only date value generated when a change occurs.
lastModified String Read-only date-time value, generated when a change occurs.
loadFeedback Boolean
loadImbalancePercentage Number Range of 0 to 1000000.
modificationComments String Maximum 4,000 characters.
name String Maximum 100 characters, ending in .akadns.net.
properties Property
resources Resource
status Status
type Enumeration Either failover-only, static, weighted, basic, or full.

Status

Member Type Description
Required
changeId String Read-only value generated when a change occurs.
message String Read-only value generated when a change occurs.
propagationStatus Enumeration Either DENIED, PENDING, or COMPLETE.
propagationStatusDate String Read-only date-time value generated when a change occurs.
passingValidation Boolean Read-only value generated when a change occurs.

Last modified: 4/6/2017