API workflow

A GTM domain requires two data centers and at least one property. Your contract determines the set of domain types that are available to you. The domain's type places a restriction on the property type you can create under a domain.

This table lists each domain type, along with the property types you can associate with them:

Property type	`failover-only`	`static`	`weighted`	`basic`	`full`
`failover`	✓	✓	✓	✓	✓
`qtr`	✓	✓	✓	✓	✓
`static`	✓	✓	✓	✓	✓
`geographic`		✓	✓	✓	✓
`cidrmapping`		✓	✓	✓	✓
`asmapping`		✓	✓	✓	✓
`weighted-round-robin`			✓	✓	✓
`weighted-hashed`			✓	✓	✓
`weighted-round-robin-load-feedback`			✓	✓	✓
`performance`				✓	✓

This sample workflow shows you how to create a new GTM domain named example.akadns.net, complete with two data centers Winterfell and Frostfangs and a property origin. You'll also see how to configure a liveness test to determine if your servers are responding to requests.

📘
When you create a new GTM domain, you may need identifiers associated with your account such as the contractId and groupId. If you need to provide IDs and don't know what they are, run List contracts or List groups for the information.

To create a new domain, run the Create a domain operation and use example.akadns.net as the domainName. This operation creates a weighted domain type named example.akadns.net, and specifies that our.admin@example.com is sent an email for each change the GTM system processes, as shown in this example. Notifications such as error messages and the domain's current propagation progress and validation status are also sent to this email address.

POST /config-gtm/v1/domains HTTP/1.1
    Accept: application/json
    Content-Type: application/json
    Content-Length: 173

        {
            "name": "example.akadns.net",
            "type": "weighted",
            "emailNotificationList": ["our.admin@example.com"],
            "modificationComments": "New Traffic Management domain."
        }

In this example, GTM confirms the domain creation with a 201 status code and returns a full representation of the new domain. Note that the API server fills in members such as defaultErrorPenalty and defaultTimeoutPenalty with default values:

HTTP/1.1 201 Created
Date: Mon, 04 Aug 2022 15:30:39 GMT
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

    {
        "resource": {
            "cidrMaps": [],
            "datacenters": [],
            "defaultErrorPenalty": 75,
            "defaultSslClientCertificate": null,
            "defaultSslClientPrivateKey": null,
            "defaultTimeoutPenalty": 25,
            "emailNotificationList": [ "our.admin@example.com" ],
            "geographicMaps": [],
            "lastModified": "2022-08-04T15:30:40.057+0000",
            "lastModifiedBy": "admin",
            "loadFeedback": false,
            "loadImbalancePercentage": null,
            "modificationComments": "New Traffic Management domain.",
            "name": "example.akadns.net",
            "properties": [],
            "resources": [],
            "status": {
                "changeId": "abb94136-dd94-4779-bfb0-fcfac67fb843",
                "message": "Change Pending",
                "passingValidation": true,
                "propagationStatus": "PENDING",
                "propagationStatusDate": "2022-08-04T15:30:40.057+0000"
            },
            "type": "weighted"
        },
        "status": {
            "changeId": "abb94136-dd94-4779-bfb0-fcfac67fb843",
            "message": "Change Pending",
            "passingValidation": true,
            "propagationStatus": "PENDING",
            "propagationStatusDate": "2022-08-04T15:30:40.057+0000"
        }
    }

Now that you created the example.akadns.net domain, run the Create a data center operation to create the first of two data centers for the domain, starting with the Winterfell data center, as shown in this example:

POST /config-gtm/v1/domains/example.akadns.net/datacenters HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 145

    {
        "city": "Downpatrick",
        "continent": "EU",
        "country": "GB",
        "latitude": 54.367,
        "longitude": -5.582,
        "nickname": "Winterfell"
    }

This operation assigns a datacenterId of 3131 to the Winterfell data center. The datacenterId is important because it's referenced by other entities across the domain and helps form the Location header that you can use to navigate directly to access the new data center. The datacenterId appears as a member in the data center's JSON response, as shown in this example:

HTTP/1.1 201 Created
Date: Mon, 04 Aug 2022 15:49:08 GMT
Location: /config-gtm/v1/domains/example.akadns.net/datacenters/3131
Transfer-Encoding: chunked
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

    {
        "resource": {
            "city": "Downpatrick",
            "cloneOf": null,
            "continent": "EU",
            "country": "GB",
            "datacenterId": 3131,
            "defaultLoadObject": null,
            "latitude": 54.367,
            "longitude": -5.582,
            "nickname": "Winterfell",
            "stateOrProvince": null,
            "virtual": true
        },
        "status": {
            "changeId": "0a580f0a-d585-4fc0-a3ff-47c79e8fd7fc",
            "message": "Change Pending",
            "passingValidation": true,
            "propagationStatus": "PENDING",
            "propagationStatusDate": "2022-08-04T15:49:10.111+0000"
        }
    }

Run the Create a data center operation again to add the Frostfangs data center, as shown in this example:

POST /config-gtm/v1/domains/example.akadns.net/datacenters HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 248

    {
        "city": "Snaefellsjokull",
        "continent": "EU",
        "country": "IS",
        "latitude": 64.808,
        "longitude": -23.776,
        "nickname": "Frostfangs"
    }

Then, run the List data centers operation to see the data centers within this domain. The Frostfangs data center is assigned a datacenterId of 3132, as shown in this example.

GET /config-gtm/v1/domains/example.akadns.net/datacenters
Content-Type: application/vnd.config-gtm.v1.0+json;charset=UTF-8

    {
        "items": [
            {
                "city": "Downpatrick",
                "cloneOf": null,
                "continent": "EU",
                "country": "GB",
                "datacenterId": 3131,
                "defaultLoadObject": {
                    "loadObject": null,
                    "loadObjectPort": 0,
                    "loadServers": null
                },
                "latitude": 54.367,
                "longitude": -5.582,
                "nickname": "Winterfell",
                "stateOrProvince": null,
                "virtual": true
            },
            {
                "city": "Snaefellsjokull",
                "cloneOf": null,
                "continent": "EU",
                "country": "IS",
                "datacenterId": 3132,
                "defaultLoadObject": {
                    "loadObject": null,
                    "loadObjectPort": 0,
                    "loadServers": null
                },
                "latitude": 64.808,
                "longitude": -23.776,
                "nickname": "Frostfangs",
                "stateOrProvince": null,
                "virtual": true
            }
        ]
    }

Run the Create or update a property operation to create 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 data center and the Frostfangs data center, as shown in this example:

PUT /config-gtm/v1/domains/example.akadns.net/properties/origin HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 534

    {
        "name": "origin",
        "handoutMode": "normal",
        "failoverDelay" : 0,
        "failbackDelay" : 0,
        "trafficTargets": [
            {
                "datacenterId": 3131,
                "enabled": true,
                "servers": [ "1.2.3.5" ],
                "weight": 50.0
            },
            {
                "datacenterId": 3132,
                "enabled": true,
                "servers": [ "1.2.3.4" ],
                "weight": 50.0
            }
        ],
        "type": "weighted-round-robin",
        "scoreAggregationType": "mean"
    }

If you'd like GTM to provide IPs for servers that respond to requests, run the Create or update a property operation again and store the livenessTests array objects as shown in this example:

PUT /config-gtm/v1/domains/example.akadns.net/properties/origin HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json
Content-Length: 982

    {
        "name": "origin",
        "handoutMode": "normal",
        "failoverDelay" : 0,
        "failbackDelay" : 0,
        "trafficTargets": [
            {
                "datacenterId": 3131,
                "enabled": true,
                "servers": [ "1.2.3.5" ],
                "weight": 50.0
            },
            {
                "datacenterId": 3132,
                "enabled": true,
                "servers": [ "1.2.3.4" ],
                "weight": 50.0
            }
        ],
        "type": "weighted-round-robin",
        "scoreAggregationType": "mean",
        "livenessTests": [
            {
                "disableNonstandardPortWarning": false,
                "hostHeader": "123.example.com",
                "httpError3xx": true,
                "httpError4xx": true,
                "httpError5xx": true,
                "name": "health-check",
                "testInterval": 60,
                "testObject": "/status",
                "testObjectPort": 80,
                "testObjectProtocol": "HTTP",
                "testTimeout": 10.0
            }
        ]
    }

With this configuration, servermonitors assigned to your domain test each IP address every 60 seconds, the testInterval, by running the equivalent of this command:

$ curl -H "Host: 123.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.