This article explains the legacy version of
This deprecated endpoint was discontinuedIdentifies an endpoint that is no longer in service. This type of endpoint should not be used. All scripts that include this type of endpoint must be updated to use a different endpoint. on 12/9/2019. If you have not already updated your scripts and applications to leverage the Get Configuration (Version 1.0) and Update Configuration (Version 1.0) endpoints, then we strongly encourage you to do so immediately.
WAF Essential cannot be configured via our APIs. However, you may leverage our APIs to retrieve WAF and Rate Limiting event log data.
Updates the entire rate limiting configuration.
Recommended Update Procedure:
The recommended procedure for fine-tuning a rate limiting configuration is outlined below.
A request to update the rate limiting configuration is described below.
HTTP Method | Request URI |
---|---|
POST |
https://api.transactcdn.com/v2/mcc/customers/AccountNumber/defend/rate_limiting/config |
Define the following term when submitting the above request:
Description | |
---|---|
Required |
|
This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.
Pass the following request body parameters:
Name | Data Type | Description |
---|---|---|
customer_id |
String |
Identifies a customer by account number. |
enabled_date |
String |
Identifies the date on which the Rate Limiting configuration was last modified. This request parameter is automatically set by the system whenever a change is applied to the configuration. As a result, this parameter will be ignored. Format: YYYY-MM-DDThh:mm:ss:ffffffZ
Example: 2022-06-30T20:42:09.330793Z
The above value represents June 30th, 2022 at 8:42 p.m. UTC. For more information on date/time format, please refer to Report Date/Time Format. |
id |
String |
Identifies the current version of the Rate Limiting configuration by a system-defined alphanumeric ID. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
|
name Required |
String |
Defines a name for the Rate Limiting configuration. This name is not exposed in the user interface. |
tuples Required |
Array |
Defines the set of rules through which Rate Limiting will be applied to site traffic. |
dimensions Required |
Array |
tuples array Determines the rule's method for grouping requests. Rate limiting is applied to grouped requests. Valid values are:
This request parameter should only be set to one of the above values. Setting it to multiple values is an invalid configuration. A list of valid values is returned by the Get Available Group Types endpoint. |
disabled Required |
Boolean |
tuples array Determines whether a rule will be enforced. Valid values are:
|
duration_sec Required |
Integer |
tuples array Determines the length, in seconds, of the rolling window that tracks the number of requests eligible for rate limiting. The rate limit formula is calculated through the limit and duration_sec request parameters as indicated below. limit requests per duration_sec
Valid values are:
|
enforcements Required |
Array |
tuples array This request parameter contains settings that define the action that will take place upon a request that has exceeded the rate limit. |
duration_sec |
Integer |
tuples array > enforcements array Defines the length of time, in seconds, that the action defined within the enforcements array will be applied to a client that violates the rate limit defined by this rule. Valid values are:
|
id |
String |
tuples array > enforcements array Indicates the system-defined alphanumeric ID assigned to the rate limiting action. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
This value is automatically set by the system whenever a change is applied to sibling or child settings. As a result, this parameter will be ignored. |
name |
String |
tuples array > enforcements array Assigns a name to the rate limiting action. |
response_body_base64 |
String |
tuples array > enforcements array Custom Response Only This parameter is only relevant when this configuration is configured to send a custom response (i.e., custom-response action) for rate limited requests. Defines the response body that will be sent to rate limited requests. This value must be Base64 encoded. Set the response body to a custom web page by specifying the desired HTML tags (e.g., <html>...</html>). |
response_headers |
Object |
tuples array > enforcements array Custom Response Only This parameter is only relevant when this configuration is configured to send a custom response (i.e., custom-response action) for rate limited requests. Contains the set of response headers that will be included in the response sent to rate limited requests. |
ResponseHeader |
String |
tuples array > enforcements array > response_headers object Custom Response Only This parameter is only relevant when this configuration is configured to send a custom response (i.e., custom-response action) for rate limited requests. Defines a response header by its name and value. This response header will be included in the response sent to rate limited requests. Syntax: "Header NameIdentifies a custom response header by its name." : "Header ValueIdentifies the value assigned to a custom response header."
Example: ... "My 1st Header" : "Value A", "My 2nd Header" : "Value B", ... |
status Required (custom-response) |
Integer |
tuples array > enforcements array Custom Response Only This parameter is required when this instance is configured to send a custom response (i.e., custom-response action) for rate limited requests. Defines the HTTP status code (e.g., 404) for the custom response that will be sent to rate limited requests. |
type Required |
String |
tuples array > enforcements array Defines the type of action that will be applied to rate limited requests. Valid values are:
Use the Get Available Action Types endpoint to retrieve a list of the available action types. |
url Required (redirect-302) |
String |
tuples array > enforcements array Redirect Only This parameter is required when this instance is configured to redirect rate limited requests. Defines the URL to which rate limited requests will be redirected. |
id |
String |
tuples array Indicates the system-defined alphanumeric ID for the rule to be updated. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
This ID is automatically updated whenever a change is applied to the Rate Limiting configuration. |
limit Required |
Integer |
tuples array Defines the number of requests that will trigger rate limiting. The rate limit formula is calculated through the limit and duration_sec request parameters as indicated below. limit requests per duration_sec
|
name Required |
String |
tuples array Assigns a name to the rule. |
rules |
Array |
tuples array This request parameter contains the set of condition groups associated with a rule. |
chained_rule |
Array |
tuples array > rules array This request parameter contains a list of match conditions. This request parameter should be empty unless the current rule contains more than one match condition. In which case, the first match condition should be defined under the operator and variable parameters that are siblings to this request parameter. |
id |
String |
tuples array > rules array > chained_rule array Identifies a rate limiting match condition by its system-defined alphanumeric ID. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
This value is automatically set by the system whenever a change is applied to sibling or child settings. As a result, this parameter will be ignored. |
operator |
Object |
tuples array > rules array > chained_rule array This request parameter contains the properties of a match condition. The variable array indicates the type of match condition being defined. |
is_negated |
Boolean |
tuples array > rules array > chained_rule array > operator object Determines whether this match condition will be satisfied when the requestThe attribute (e.g., hostname, URL path, IP address, etc.) of the request that will be compared is determined by the variable array. matches or does not match the value defined by the values parameter. Valid values are:
|
String |
tuples array > rules array > chained_rule array > operator object Determines how the system will interpret the case-sensitive comparison between the requestThe attribute (e.g., hostname, URL path, IP address, etc.) of the request that will be compared is determined by the variable array. and the values parameter. Valid values:
A list of valid values is returned by the Get Available Match Comparison Type endpoint. View legacy match types.
The following match types have undergone end-of-life and should not be used:
|
|
value Deprecated |
String |
tuples array > rules array > chained_rule array > operator object This parameter has undergone end-of-life. Please use the values parameter instead. Defines a value that will be used to identify requests that are eligible for rate limiting. |
values Required |
Array |
tuples array > rules array > chained_rule array > operator object Defines one or more values through which requests that are eligible for rate limiting will be identified. |
variable |
Array |
tuples array > rules array > chained_rule array This request parameter defines the type of match condition. |
match |
Array |
tuples array > rules array > chained_rule array > variable array This parameter defines the subcategory associated with a match condition. Only the "Request Headers" and "Request Method" match conditions support subcategories. |
String |
tuples array > rules array > chained_rule array > variable array > match array Defines the match condition's subcategory (e.g., User-Agent). Valid values are reported by the value element of the valid_values array returned by the Get Available Match Condition Types endpoint. |
|
type |
String |
tuples array > rules array > chained_rule array > variable array Defines the type of match condition (e.g., REQUEST_HEADERS). Valid values are reported by the type parameter in the Get Available Match Condition Types endpoint. |
id |
String |
tuples array > rules array Indicates the system-defined alphanumeric ID of a condition group. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
This value is automatically set by the system whenever a change is applied to sibling or child settings. As a result, this parameter will be ignored. |
name |
String |
tuples array > rules array Assigns a name to the condition group. |
operator |
Object |
tuples array > rules array This request parameter contains the first match condition associated with a condition group. The variable array, which is a sibling to this parameter, indicates the type of match condition being defined. |
is_negated |
Boolean |
tuples array > rules array > operator object Determines whether this match condition will be satisfied when the requestThe attribute (e.g., hostname, URL path, IP address, etc.) of the request that will be compared is determined by the variable array. matches or does not match the value defined by the values parameter. Valid values are:
|
String |
tuples array > rules array > operator object Determines how the system will interpret the case-sensitive comparison between the requestThe attribute (e.g., hostname, URL path, IP address, etc.) of the request that will be compared is determined by the variable array. and the values parameter. Valid values:
A list of valid values is returned by the Get Available Match Comparison Type endpoint. View legacy match types.
The following match types have undergone end-of-life and should not be used:
|
|
value Deprecated |
String |
tuples array > rules array > chained_rule array > operator object This parameter has undergone end-of-life. Please use the values parameter instead. Defines a value that will be used to identify requests that are eligible for rate limiting. |
values Required |
Array |
tuples array > rules array > operator object Defines one or more values used to identify requests that are eligible for rate limiting. |
variable |
Array |
tuples array > rules array This request parameter describes the type of match condition. |
match |
Array |
tuples array > rules array > variable array This parameter defines the subcategory associated with a match condition. Only the "Request Headers" and "Request Method" match conditions support subcategories. |
String |
tuples array > rules array > variable array > match array Defines the match condition's subcategory (e.g., User-Agent). Valid values are reported by the value element of the valid_values array returned by the Get Available Match Condition Types endpoint. |
|
type |
String |
tuples array > rules array > variable array Defines the type of match condition (e.g., REQUEST_HEADERS). Valid values are reported by the type parameter in the Get Available Match Condition Types endpoint. |
scope |
Object |
tuples array Contains the scope for the current rule. |
host |
Object |
tuples array > scope object Contains hostname criteria that defines the set of requests eligible for rate limiting by the current rule. |
is_negated |
Boolean |
tuples array > scope object > host object Determines whether this scope condition will be satisfied when the host defined in the request URL matches or does not match the value defined by the value|values parameter. Valid values are:
|
type |
String |
tuples array > scope object > host object Determines how the system will interpret the comparison between the request's hostname and the value defined within the value | values parameter. Valid values:
Apply this rate limit across all hostnames by setting this parameter to "GLOB" and setting the value parameter to "*." This type of configuration is also known as "Default." View legacy match types.
The following match type has undergone end-of-life and should not be used:
|
value |
String |
tuples array > scope object > host object This parameter is required when the type parameter is set to one of the following values: GLOB or REGEX. Otherwise, it should not be included. Identifies a value that will be used to identify requests that are eligible for rate limiting. |
values |
Array String values |
tuples array > scope object > host object This parameter is required when the type parameter is set to "EM." Otherwise, it should not be included. Identifies one or more values used to identify requests that are eligible for rate limiting. |
path |
Object |
tuples array > scope object Contains URL path criteria that defines the set of requests eligible for rate limiting by the current rule. |
is_negated |
Boolean |
tuples array > scope object > path object Determines whether this scope condition will be satisfied when the request's URL path matches or does not match the value defined by the value | values parameter. Valid values are:
|
type |
String |
tuples array > scope object > path object Determines how the system will interpret the comparison between the request's URL path and the value defined within the value | values parameter. Valid values:
Apply this rate limit across all request URLs by setting this parameter to "GLOB" and setting the value parameter to "*." This type of configuration is also known as "Default." View legacy match types.
The following match type has undergone end-of-life and should not be used:
|
value |
String |
tuples array > scope object > path object This parameter is required when the type parameter is set to one of the following values: GLOB or REGEX. Otherwise, it should not be included. Identifies a value that will be used to identify requests that are eligible for rate limiting. |
values |
Array String values |
tuples array > scope object > path object This parameter is required when the type parameter is set to "EM." Otherwise, it should not be included. Identifies one or more values used to identify requests that are eligible for rate limiting. |
type Required |
String |
Set this request parameter to "ddos-coordinator." |
The response to the above request includes an HTTP status code, response headers, and a response body.
A status code indicates whether the request was successfully performed.
The response for this endpoint only includes standard HTTP response headers.
The response body for a successful request contains the following response parameter:
Name | Data Type | Description |
---|---|---|
success |
Boolean |
Indicates whether the Rate Limiting configuration was updated. Valid values are:
|
job_id End-of-Life |
String |
Indicates the system-defined ID assigned to the rate limiting configuration update. |
The response body for an unsuccessful request will contain an error response that provides additional information.
A sample JSON request is shown below.
POST https://api.transactcdn.com/v2/mcc/customers/0001/defend/rate_limiting/config HTTP/1.1
Authorization: TOK:12345678-1234-1234-1234-1234567890ab
Accept: application/json
Content-Type: application/json
Host:api.transactcdn.com
Content-Length: 1229
{ "customer_id": "0001", "enabled_date": "2018-04-03T23:52:24.590818Z", "id": "e0fa44b4-ede1-4056-8bfe-5daa481a26c10001", "name": "name", "tuples": [{ "dimensions": [ "IP", "USER_AGENT" ], "disabled": true, "duration_sec": 60, "enforcements": [{ "duration_sec": 60, "id": "de7cd68c-b41e-4305-9202-3443515df8190001", "name": "Rate Limiting Action", "type": "redirect-302", "url": "http://sec.example.com/unavailable.html" } ], "id": "1824dd0f-7791-41f7-86de-80817760f4240001", "limit": 100, "name": "Rate Limiting Rule", "rules": [{ "chained_rule": [], "id": "31385b47-5f5a-41d7-90ab-d891b28a8ca80001", "name": "Condition Group", "operator": { "is_negated": false, "type": "EM", "values": [ "http://cdn.example.com/index.php" ] }, "variable": [{ "type": "REQUEST_URI" } ] } ], "scope": { "host": { "is_negated": false, "type": "PM", "values": [ "www.example.com" ] }, "path": { "is_negated": false, "type": "GLOB", "value": "*" } } } ], "type": "ddos-coordinator" }
A sample JSON response is shown below.
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json; charset=utf-8
Date: Thu, 15 Apr 2021 12:00:00 GMT
Content-Length: 80
{ "success" : true, "job_id" : "" }