GreenArrow Documentation

Throttling Templates API

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
}