Throttling Templates API

Table of Contents
Overview
Attributes
Throttling Templates
Throttling Rules

Overview

Throttling Templates are a named group of Throttling Rules. Each Throttling Rule contains a list of domains to which it applies. Throttling Templates are used by IP Addresses to provide a default list of Throttling Rules.

See Dynamic Delivery for more information on how Dynamic Delivery operates.

Attributes

The following attributes are defined for Throttling Templates:

throttling_template
hash
/
required

id
integer
/
read-only

An automatically generated identifier.

name
string
/
required

A descriptive name to associate with this Throttling Template.

Must be unique (case-insensitive)
Must be from 1 to 200 characters in length
Must contain at least one letter or number

rules
array
/
default: []

A list of throttling rules. A Throttling Template may contain up to 250 throttling rules.

id
integer
/
read-only

The internal identifier for this rule row. Use this value when calling the Update Throttling Rule endpoint.

domains
array of strings
/
required

The list of domains to which this rule applies.

If a domain is prefixed with [*.], it will apply to itself and any subdomain. For example, [*.]web.example.com will match web.example.com, second.web.example.com, and third.second.web.example.com.

If a domain is prefixed with *., it will apply to any subdomain, but not itself. For example, *.web.example.com will match second.web.example.com and third.second.web.example.com but not web.example.com.

Must be valid domain names
Must contain at least one domain name
Must be unique (case-insensitive) across all rules in this template

max_concurrent_connections
integer
/
required

The maximum number of connections allowed to each domain in this rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

max_messages_per_hour
integer
/
required

The maximum number of messages per hour allowed to each domain in this rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

throttle_program
hash
/
default: null

The Throttle Program to use on this rule. Set to null to use no Throttle Program.

If this is non-null, the requested Throttle Program must exist.

id
integer

The identifier of the Throttle Program.

name
string

The descriptive name for the Throttle Program. If this is specified to set the Throttle Program for this Throttling Rule, the Throttle Program is found with a case-insensitive search.

If both id and name are present when creating or updating a rule, the value in name is ignored and the requested program will only be found by its id.

default
hash
/
required

max_concurrent_connections
integer
/
required

The maximum number of connections allowed to domains not specified in a rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

max_messages_per_hour
integer
/
required

The maximum number of messages per hour allowed to domains not specified in a rule.

The value 0 is treated as unlimited.

Must be an integer greater than or equal to 0.

Throttling Templates

Get a List of Throttling Templates

GET /ga/api/v3/eng/throttling_templates
GET /ga/api/v3/eng/throttling_templates?page={page}
GET /ga/api/v3/eng/throttling_templates?page_token={page_token}

Parameters

page integer / optional	The page number to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` can be used to retrieve the next page of results.

Response

The response will contain a list of Throttling Templates in the following format.

throttling_templates
array of hashes

id integer	An automatically generated identifier.
name string	A descriptive name for this Throttling Template.

pagination
hash

page integer	The page number of this result set. Page numbers start at 0.
per_page integer	The number of records returned on each page.
num_pages integer	The total number of pages in the result set.
num_records integer	The total number of records that are in the result set.
next_page_token string	A unique identifier that can be used to retrieve the next result set. `null` is returned if this is the last page.

Example

GET /ga/api/v3/eng/throttling_templates

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_templates": [
      {
        "id": 1,
        "name": "Basic Template"
      },
      {
        "id": 2,
        "name": "Second Template"
      },
      {
        "id": 3,
        "name": "Third Template"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a Single Throttling Template

GET /ga/api/v3/eng/throttling_templates/{id}

Response

The response will contain details on the requested record:

throttling_template
hash

The attributes for this hash are defined in the Attributes section of this document.

Example

GET /ga/api/v3/eng/throttling_templates/10

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_template": {
      "id": 10,
      "name": "Basic Template",
      "rules": [
        {
          "id": 7,
          "domains": [
            "example-2.com",
            "example-1.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 0,
          "throttle_program": null
        },
        {
          "id": 8,
          "domains": [
            "example-6.com",
            "example-7.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 500,
          "throttle_program": null
        }
      ],
      "default": {
        "max_concurrent_connections": 1,
        "max_messages_per_hour": 60
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

List the References to a Throttling Template

GET /ga/api/v3/eng/throttling_templates/{id}/used_by
GET /ga/api/v3/eng/throttling_templates/{id}/used_by?page={page}
GET /ga/api/v3/eng/throttling_templates/{id}/used_by?page_token={page_token}

Parameters

page integer / optional	The page number to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` can be used to retrieve the next page of results.

Response

used_by
array of hashes

A list of objects that use this Throttling Template.

type
string

The type of object.

May be: ip_address

id
integer

The unique identifier for the object.

name
string

The user-supplied case-insensitive unique identifier for the object.

pagination
hash

page integer	The page number of this result set. Page numbers start at 0.
per_page integer	The number of records returned on each page.
num_pages integer	The total number of pages in the result set.
num_records integer	The total number of records that are in the result set.
next_page_token string	A unique identifier that can be used to retrieve the next result set. `null` is returned if this is the last page.

Example

GET /ga/api/v3/eng/throttling_templates/1/used_by

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "used_by": [
      {
        "type": "ip_address",
        "id": 2,
        "name": "ipaddr-1"
      },
      {
        "type": "ip_address",
        "id": 3,
        "name": "ipaddr-2"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 2,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a Throttling Template

POST /ga/api/v3/eng/throttling_templates

Payload

The JSON data sent to this endpoint should contain an object as described in the Attributes section of this page.

All required fields must be present. Do not specify read-only fields.

Response

The response will include a data key containing the full Throttling Template record as defined in the Throttling Template Attributes.

Example

POST /ga/api/v3/eng/throttling_templates

{
  "throttling_template": {
    "name": "Example Throttling Template",
    "rules": [
      {
        "domains": [
          "example-2.com",
          "example-1.com"
        ],
        "max_concurrent_connections": 2,
        "max_messages_per_hour": 0,
        "throttle_program": {
          "id": 1,
          "name": "this name doesn't exist"
        }
      },
      {
        "domains": [
          "example-6.com",
          "example-7.com"
        ],
        "max_concurrent_connections": 0,
        "max_messages_per_hour": 500,
        "throttle_program": {
          "name": "Automatic Backoff"
        }
      }
    ],
    "default": {
      "max_concurrent_connections": 1,
      "max_messages_per_hour": 60
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_template": {
      "id": 16,
      "name": "Example Throttling Template",
      "rules": [
        {
          "id": 11,
          "domains": [
            "example-2.com",
            "example-1.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 0,
          "throttle_program": {
            "id": 1,
            "name": "Automatic Backoff"
          }
        },
        {
          "id": 12,
          "domains": [
            "example-6.com",
            "example-7.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 500,
          "throttle_program": {
            "id": 1,
            "name": "Automatic Backoff"
          }
        }
      ],
      "default": {
        "max_concurrent_connections": 1,
        "max_messages_per_hour": 60
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Throttling Template

PUT /ga/api/v3/eng/throttling_templates/{id}

Payload

throttling_template
hash
/
required

This hash is described in the Attributes section of this page, with the exceptions described below.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Exceptions:

rules array of hashes	This key may not be specified when updating existing Throttling Templates. See the Update a Throttling Rule and Delete a Throttling Rule sections for information on modifying existing rules.
rules_new array of hashes	Any rules provided in this key is treated as new rules to add to the Throttling Template. If any domains provided in those rules already exist in the Throttling Template, this will result in a validation error due to the duplicate domains.

Response

The response will include a data key containing the full Throttling Template record as defined in the Throttling Template Attributes.

Example

PUT /ga/api/v3/eng/throttling_templates/17

{
  "throttling_template": {
    "name": "my new name",
    "rules_new": [
      {
        "domains": [
          "new-rule-domain.com"
        ],
        "max_concurrent_connections": 7,
        "max_messages_per_hour": 1056
      }
    ]
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_template": {
      "id": 17,
      "name": "my new name",
      "rules": [
        {
          "id": 13,
          "domains": [
            "example-2.com",
            "example-1.com"
          ],
          "max_concurrent_connections": 2,
          "max_messages_per_hour": 0,
          "throttle_program": null
        },
        {
          "id": 14,
          "domains": [
            "example-6.com",
            "example-7.com"
          ],
          "max_concurrent_connections": 0,
          "max_messages_per_hour": 500,
          "throttle_program": null
        },
        {
          "id": 15,
          "domains": [
            "new-rule-domain.com"
          ],
          "max_concurrent_connections": 7,
          "max_messages_per_hour": 1056,
          "throttle_program": null
        }
      ],
      "default": {
        "max_concurrent_connections": 1,
        "max_messages_per_hour": 60
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Throttling Template

DELETE /ga/api/v3/eng/throttling_templates/{id}

Throttling Templates that are currently used by other records may not be deleted. Use the Throttling Templates API to get a list of such records.

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/throttling_templates/30

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}

Throttling Rules

Create a Throttling Rule

POST /ga/api/v3/eng/throttling_templates/{throttling_template_id}/throttling_rules

Parameters

throttling_template_id
integer
/
required

The id for a Throttling Template as supplied when querying the list of Throttling Templates.

Payload

throttling_rule
hash
/
required

The structure of this hash is the same as the entries defined in the rules array under Throttling Template Attributes.

All required fields must be present. Do not specify read-only fields.

Response

The response will include a throttling_rule key containing a hash that uses the structure defined in the Throttling Template Attributes.

Example

POST /ga/api/v3/eng/throttling_templates/3/throttling_rules

{
  "throttling_rule": {
    "domains": [
      "new-domain-1.com",
      "new-domain-2.com"
    ],
    "max_concurrent_connections": 7,
    "max_messages_per_hour": 9
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_rule": {
      "id": 3,
      "domains": [
        "new-domain-1.com",
        "new-domain-2.com"
      ],
      "max_concurrent_connections": 7,
      "max_messages_per_hour": 9,
      "throttle_program": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a Throttling Rule

PUT /ga/api/v3/eng/throttling_templates/{throttling_template_id}/throttling_rules/{rule_id}

Parameters

throttling_template_id integer / required	The `id` for a Throttling Template as supplied when querying the list of Throttling Templates.
rule_id integer / required	The `id` for a Throttling Rule as supplied in the `rules` array when querying details on a single Throttling Template.

Payload

throttling_rule
hash
/
required

The structure of this hash is the same as the entries defined in the rules array under Throttling Template Attributes.

Response

The response will include a throttling_rule key containing a hash that uses the structure defined in the Throttling Template Attributes.

Example

PUT /ga/api/v3/eng/throttling_templates/4/throttling_rules/4

{
  "throttling_rule": {
    "domains": [
      "new-domain-1.com",
      "new-domain-2.com"
    ],
    "max_concurrent_connections": 7,
    "max_messages_per_hour": 9
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "throttling_rule": {
      "id": 4,
      "domains": [
        "new-domain-1.com",
        "new-domain-2.com"
      ],
      "max_concurrent_connections": 7,
      "max_messages_per_hour": 9,
      "throttle_program": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a Throttling Rule

Use this endpoint to remove a rule from a Throttling Template.

DELETE /ga/api/v3/eng/throttling_templates/{throttling_template_id}/throttling_rules/{rule_id}

Parameters

throttling_template_id integer / required	The `id` for a Throttling Template as supplied when querying the list of Throttling Templates.
rule_id integer / required	The `id` for a Throttling Rule as supplied in the `rules` array when querying details on a single Throttling Template.

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/throttling_templates/19/throttling_rules/14

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}