Global Traffic Management Load Feedback API v1

POST load data for a Global Traffic Management (GTM) domain and GET the current load state.

Learn more:


Overview

The Global Traffic Management Load Feedback API is an upcoming offering. It is not available for use yet, but this document describes the API and how to use it. We encourage prospective users to review these documents and submit feedback via our Community page.

The Global Traffic Management Load Feedback API allows users to submit load data for a GTM domain in either JSON or XML format via POST, and to fetch the current load state via GET.

This document assumes a working knowledge of the Global Traffic Management system, DNS-based load balancing, and load feedback. If you would like more background on any of those topics before proceeding, please see the Resources section.

The GTM Load Feedback API lets you update GTM’s load data in real time, for faster, more accurate load balancing. To use the API, you describe the load conditions in one of your domain’s traffic targets (data centers, also known as regions), for a resource (a resource is anything that might constrain traffic, e.g., bandwidth or connections per second). The API supports XML and JSON data formats, both of which feature the following members:

Member Type Description
Required
domain String The name of the domain being updated, e.g., example.akadns.net.
datacenterId Number The number of the datacenter (traffic target) being updated. This number comes from the Akamai code field in the Luna Control Center. To support legacy clients, we accept region as an alias for datacenterId; either tag may be used.
resource String The name of the resource that is being used to balance load. This can be any quantity you define. For example, a resource can represent connections to a database, bandwidth, hits, or anything else. Please see the API’s Resources section for details.
current-load Number The current load on the resource in the given datacenter. For example, if the resource is database connections, and you have 50 connections, you would report 50 for this value.
target-load Number GTM’s load balancer will begin to shift traffic away from a traffic target when the current-load exceeds the target-load. For example, if you want traffic to begin shifting away from a database location when it has 100 connections, you would set target-load to 100.
max-load Number If the load in every datacenter exceeds its target, GTM will raise targets proportional to the difference between max-load and target-load. Set max-load higher in data centers that can handle more traffic when the whole system is overloaded.
timestamp String This should be the time at which the load was recorded, in XSD date format.

The URL to which you should POST this data has the following format:

/gtm-load-data/v1/domain/resource/datacenterId

Here, domain is the domain name, resource is the resource name, and datacenterId is the ID of the datacenter.

Let’s say your GTM domain is called example.akadns.net, and you have a resource called connections that constrains load according to the number of HTTP connections to a datacenter. You want to report the load in a datacenter with ID number 100. The current load in datacenter 100 is 20, the target is 25, and the max is 30. You can submit that data to our system with the following JSON:

PUT /gtm-load-data/v1/example.akadns.net/connections/100 HTTP/1.1
Content-type: application/json
Content-length: 190

{
     "domain": "example.akadns.net",
     "datacenterId": 100,
     "resource": "connections",
     "timestamp": "2015-05-01T19:38:53.188Z",
     "current-load": 20,
     "target-load": 25,
     "max-load": 30
}

The same load update in XML format would look like this:

PUT /gtm-load-data/v1/example.akadns.net/connections/100 HTTP/1.1
Content-type: application/xml
Content-length: 250

<load-object domain="example.akadns.net" timestamp="2015-05-01T19:38:53.188Z" version="1" xmlns="http://www.akamai.com/FirstPoint/load-balancing">
   <datacenter datacenterId="100">
       <resource name="connections">
           <current-load>20</current-load>
           <target-load>25</target-load>
   <max-load>30</max-load>
   </resource>
   </datacenter>
</load-object>

You may also fetch load data, in either XML or JSON format, using a GET request. You indicate your preferred format (JSON or XML) in the Accept header; if that header is missing, we default to JSON. Note that when you fetch data, the load numbers will reflect GTM’s current internal state. That state may differ from the most recent data you submitted, because load data takes a few seconds to propagate through the system.

Resources

The Traffic Management Load Feedback API is an upcoming offering. It is not available for use yet, but this document describes the API and how to use it. We encourage prospective users to review these documents and submit feedback via our Community page.

The Akamai Global Traffic Management (GTM) has an optional feature called load feedback. With load feedback, load balancing is controlled by measurements of entities, which you define, called resources. GTM names are grouped by domain (for example, example.akadns.net). Within a domain, you may have any number of properties, or fully qualified names (e.g., images.example.akadns.net). Network traffic is balanced between data centers, also known as regions or traffic targets.

A resource is anything that is consumed by load on a data center, and is measured and reported to improve load balancing. As an example, for a database application, you might decide that the most important measurement of load is queries per second. For a static web server, you might choose to measure HTTP GET requests per second. A resource is simply a name for something you measure that reflects how you want to balance load across your datacenters. You report the load in whatever units make sense to you; to GTM, loads are just relative unit-less quantities. A resource may constrain a single property, or all properties in a domain.

An instance of a resource represents the current, target, and maximum load configured for a particular data center.

For a full description of GTM, our DNS-based load balancing, and all the terms used here, please see the GTM integration guide, and for documentation of all aspects of GTM’s API, please see the GTM API guide.

API summary

Operation Method Endpoint
Submit Load Data POST /gtm-load-data/v1/{domain}/{resource}/{datacenterId}
Fetch Load Data GET /gtm-load-data/v1/{domain}/{resource}/{datacenterId}

Submit load data

Use this action to submit load data. The URI specifies the domain, resource, and datacenterId of the instance to which the load data pertains. The data may be submitted in either XML or JSON format. To support legacy clients, we allow region as an alias for datacenterId. The timestamp string should be in XSD format.

In the examples that follow, we’ll assume you have a GTM domain called example.akadns.net. Within this domain, you have a resource called connections, which reports the number of HTTP connections in a datacenter. In these examples, we will update and check the load data for the connections resource datacenter number 100.

POST /gtm-load-data/v1/{domain}/{resource}/{datacenterId}

Example: /gtm-load-data/v1/example.akadns.net/connections/100

Content-Type: application/json

Request:

{
    "domain": "example.akadns.net",
    "datacenterId": 100,
    "resource": "connections",
    "timestamp": "2015-05-01T19:38:53.188Z",
    "current-load": 20,
    "target-load": 25,
    "max-load": 30
}

POST /gtm-load-data/v1/{domain}/{resource}/{datacenterId}

Example: /gtm-load-data/v1/example.akadns.net/connections/100

Content-Type: application/xml

Request:

<load-object domain="example.akadns.net" timestamp="2015-05-01T19:38:53.188Z" version="1" xmlns="http://www.akamai.com/FirstPoint/load-balancing">
    <datacenter datacenterId="100">
        <resource name="connections">
            <current-load>20</current-load>
            <target-load>25</target-load>
            <max-load>30</max-load>
        </resource>
    </datacenter>
</load-object>

Parameter Type Sample Description
Required
datacenterId Number 100 The ID number for the datacenter (traffic target), from the “Akamai code” field in the Luna Control Center.
domain String example.akadns.net The name of the GTM domain
resource String connections The name of the resource

Status 204

Fetch load data

Use this action to fetch the load data for a resource instance. The URI format is the same as the POST action. The API will return either XML or JSON, depending on your Accept header (if both are specified, or there is no Accept header, we default to JSON). In this sample data, we’re fetching load for a resource called connections in datacenter 100, in the domain example.akadns.net.

GET /gtm-load-data/v1/{domain}/{resource}/{datacenterId}

Example: /gtm-load-data/v1/example.akadns.net/connections/100

Parameter Type Sample Description
Required
datacenterId Number 100 The ID number for the datacenter (traffic target), from the “Akamai code” field in the Luna Control Center.
domain String example.akadns.net The name of the GTM domain
resource String connections The name of the resource

Status 200 application/json

Headers:

  • Accept: application/json

Response:

{
    "domain": "example.akadns.net",
    "datacenterId": 100,
    "resource": "connections",
    "timestamp": "2015-05-01T19:38:53.188Z",
    "current-load": 20,
    "target-load": 25,
    "max-load": 30
}

Status 200 application/xml

Headers:

  • Accept: application/xml

Response:

<load-object domain="example.akadns.net" timestamp="2015-05-01T19:38:53.188Z" version="1" xmlns="http://www.akamai.com/FirstPoint/load-balancing">
    <datacenter datacenterId="100">
        <resource name="connections">
            <current-load>20</current-load>
            <target-load>25</target-load>
            <max-load>30</max-load>
        </resource>
    </datacenter>
</load-object>

Errors

Code Message Description
400 Invalid URI This error indicates that the URI did not have the correct format, which is specified in this document. The response JSON detail field will have more details on which part of the URI was missing.
400 Bad Datacenter ID The datacenterId number must be a positive integer. This error indicates that the number could not be parsed as a positive integer.
400 XML Invalid or Missing This error occurs if the system is unable to parse XML load data that it receives in a POST. This might be because the data is missing or the XML is not well formed. This error can also occur if the data is formatted badly or exceeds configured limits (for example, negative load values).
400 JSON Invalid or Missing This error occurs if the system is unable to parse JSON load data that it receives in a POST, either because the data is missing or the JSON is not well formed. This error can also occur if the data is formatted badly or exceeds configured limits (for example, negative load values).
400 Bad Timestamp This error is returned when the timestamp is missing, invalid, or more than a few minutes in the future. Timestamps should be in XSD format, e.g., 2015-05-01T19:38:53.698.188Z If a different format is used, this error will be returned.
400 URI/Data Mismatch This error occurs when the domain, resource, or datacenterId in the XML or JSON does not match the corresponding parts of the URI. The detail string in the JSON error object shows both the XML/JSON and the URI values, so you can see which ones do not match.
400 Target Exceeds Capacity The target-load should never exceed the max-load. If it does, this error is returned.
400 Missing Allowed Domains Header Requests to read and write a domain’s data must have a header that indicates the Luna client ID, which is then matched against a list of allowed domains. If the header is missing, this error is returned. In general, the Akamai system should supply this header for you; if you get this error, it might indicate a misconfiguration.
403 Invalid Domain This error is returned when the domain is not configured, or does not have load feedback configured.
403 Domain Not Allowed This error indicates that the Luna user who submitted a request did not have permission to read or modify the GTM domain.
403 No Resource Instance For a load tuple to be valid, the resource must be configured in the given datacenter. For example, if you have three database servers, each constrained by number of connections, you might configure the “numconns” resource in three datacenters, each representing a database server. This error would fire if you attempted to update load in some other datacenters, not one of those three.
403 Not a Push Resource The resource exists, but it’s not configured to use the REST load push API.
403 Requested Data Not Found In Body This error occurs when the XML or JSON does not contain data for the resource or datacenter specified in the URI.
404 No Data This error only pertains to a GET request: it occurs when the system does not have data available for a valid domain/datacenterId/resource tuple. If you get this error, try waiting a minute or so and then repeating the query. If that does not work, make sure you have submitted data for that tuple before. If that still does not work, please contact Akamai Technical Support.
405 Bad Method This error occurs when any HTTP or HTTPS method other than POST or GET is used.
405 Bad Version This error occurs when a non-supported version is specified in the URI. Currently, the only supported version is v1.
429 Too Many Requests The Traffic Management Load Feedback API imposes a rate limit on requests: by default, we limit each domain to 60 updates per minute. If that limit is exceeded, the system returns this error.
500 Internal Server Error The system returns this error when it encounters an internal problem.