API workflow

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