Traffic Management Load Feedback API

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

Overview

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.

Error Responses

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 Customer Care.
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.

Last modified: 12/12/2016