This article explains the legacy version of
WAF Essential cannot be configured via our APIs. However, you may leverage our APIs to retrieve WAF and Rate Limiting event log data.
Updates your 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/waf/v1.0/limits |
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 enabled. 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
|
last_modified_date |
String |
Identifies the date on which the Rate Limiting configuration was last modified. 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. |
name Required |
String |
Defines the name assigned to the Rate Limiting configuration. |
limits Required |
Array Objects |
Contains a list of rules. |
id |
String |
limits array Indicates the system-defined alphanumeric ID for the current rule. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
|
name Required |
String |
limits array Indicates the name of the rule. |
disabled Required |
Boolean |
limits array Indicates whether a rule will be enforced. Valid values are:
|
keys |
Array String values |
limits array Indicates the method by which the current rule groups requests. Rate limiting is applied to grouped requests. Valid values are:
|
Required |
Integer |
limits array Indicates 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 num and duration_sec properties as indicated below. num requests per duration_sec
Valid values are: 1 | 5 | 10 | 30 | 60 | 120 | 300
|
Required |
Integer |
limits array Indicates the rate limit value. This value identifies the number of requests that will trigger rate limiting. The rate limit formula is calculated through the num and duration_sec properties as indicated below. num requests per duration_sec
|
action Required |
Object |
limits array Contains settings that define the action that will take place upon a request that has exceeded the rate limit. |
id |
String |
limits array > action object Indicates the system-defined alphanumeric ID assigned to the rate limiting action. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
|
name |
String |
limits array > action object Indicates the name assigned to the rate limiting action. |
Required |
String |
limits array > action object Indicates the type of action that will be applied to rate limited requests. Valid values are:
|
duration_sec |
Integer |
limits array > action object Indicates the length of time, in seconds, that the action defined within the action object will be applied to a client that violates the rate limit defined by this rule. Valid values are: 10 | 60 | 300
|
response_body_base64 |
String |
limits array > action object Indicates the response body that will be sent to rate limited requests. This value is Base64 encoded. |
response_headers |
Array Objects |
limits array > action object Contains the set of headers that will be included in the response sent to rate limited requests. |
key |
String |
limits array > action object > response_headers object Identifies the name of the response header that will be included in the custom response sent to rate limited requests. |
value |
String |
limits array > action object > response_headers object Indicates the value for the response header that will be included in the custom response sent to rate limited requests. |
status Required for custom-response |
Integer |
limits array > action object Indicates the HTTP status code (e.g., 404) for the custom response sent to rate limited requests. |
url Required for redirect-302 |
String |
limits array > action object Indicates the URL to which rate limited requests will be redirected. |
condition_groups |
Array Objects |
limits array Contains the set of condition groups associated with a rule. |
id |
String |
limits array > condition_groups array Indicates the system-defined alphanumeric ID of a condition group. Example: 12345678-90ab-cdef-ghij-klmnopqrstuvwxyz1
|
name |
String |
limits array > condition_groups array Indicates the name of a condition group. |
conditions Required for condition_groups |
Array Objects |
limits array > condition_groups array Contains a list of match conditions. |
op Required for condition_groups |
Object |
limits array > condition_groups array > conditions array Contains the properties of a match condition. The type of match condition is determined by the target property. |
is_case_insensitive |
Boolean |
limits array > condition_groups array > conditions array > op object Indicates whether the 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 property is case-sensitive. Valid values are:
|
is_negated |
Boolean |
limits array > condition_groups array > conditions array > op object Indicates 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 property. Valid values are:
|
type Required for condition_groups |
String |
limits array > condition_groups array > conditions array > op object Indicates 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 property. Valid values:
|
value Required for RX |
String |
limits array > condition_groups array > conditions array > op object Identifies a regular expression used to identify requests that are eligible for rate limiting. |
values Required for EM or IPMATCH |
Array String values |
limits array > condition_groups array > conditions array > op object Identifies one or more values used to identify requests that are eligible for rate limiting. If you are matching requests by IP address, make sure to use standard IPv4 and CIDR notation. |
target Required for condition_groups |
Object |
limits array > condition_groups array > conditions array Describes the type of match condition. |
type Required for condition_groups |
String |
limits array > condition_groups array > conditions array > target object Determines how requests will be identified. Valid values are: FILE_EXT | REMOTE_ADDR | REQUEST_HEADERS | REQUEST_METHOD | REQUEST_URI
|
Required for request-headers |
String |
limits array > condition_groups array > conditions array > target object. request-headers only Indicates the name of the request header through which requests will be identified. Valid values are: Host | Referer | User-Agent
|
scope |
Object |
limits array Contains the scope for the current rule. |
host |
Object |
limits array > scope object Contains hostname criteria that defines the set of requests eligible for rate limiting by the current rule. |
is_case_insensitive |
Boolean |
limits array > scope object > host object Indicates whether the comparison between the host defined in the request URL and the value defined by the value | values property is case-sensitive. Valid values are:
|
is_negated |
Boolean |
limits array > scope object > host object Indicates 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 property. Valid values are:
|
type |
String |
limits array > scope object > host object Indicates how the system will interpret the comparison between the request's hostname and the value defined within the value | values property. Valid values:
Apply this rate limit across all hostnames by setting this property to "GLOB" and setting the value property to "*." This type of configuration is also known as "Default." |
value Required for GLOB or RX |
String |
limits array > scope object > host object Identifies a value that will be used to identify requests that are eligible for rate limiting. |
values Required for EM |
Array String values |
limits array > scope object > host object Identifies one or more values used to identify requests that are eligible for rate limiting. |
path |
Object |
limits array > scope object Contains URL path criteria that defines the set of requests eligible for rate limiting by the current rule. |
is_case_insensitive |
Boolean |
limits array > scope object > path object Indicates whether the comparison between the request's URL path and the value defined by the value | values property is case-sensitive. Valid values are:
|
is_negated |
Boolean |
limits array > scope object > path object Indicates 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 property. Valid values are:
|
type |
String |
limits array > scope object > path object Indicates how the system will interpret the comparison between the request's URL path and the value defined within the value | values property. Valid values:
Apply this rate limit across all request URLs by setting this property to "GLOB" and setting the value property to "*." This type of configuration is also known as "Default." |
value Required for GLOB or RX |
String |
limits array > scope object > path object Identifies a value that will be used to identify requests that are eligible for rate limiting. |
values Required for EM |
Array String values |
limits array > scope object > path object Identifies one or more values used to identify requests that are eligible for rate limiting. |
type |
String |
Set this property to CONFIG. |
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 |
---|---|---|
id |
String |
Indicates your customer account number. |
status |
String |
Returns success upon successfully updating your Rate Limiting configuration. |
success |
Boolean |
Indicates whether the Rate Limiting configuration was updated. Valid values are:
|
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/waf/v1.0/limits HTTP/1.1
Authorization: TOK:12345678-1234-1234-1234-1234567890ab
Accept: application/json
Content-Type: application/json
Host:api.transactcdn.com
Content-Length: 820
{ "name": "Rate Limiting", "limits": [{ "action": { "type": "drop-request" }, "disabled": false, "duration_sec": 5, "num": 30000, "name": "Drop Requests", "condition_groups": [{ "conditions": [{ "op": { "type": "EM", "values": [ ".aspx" ] }, "target": { "type": "FILE_EXT" } } ] } ] } ] }
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: 70
{ "id": "0001", "status": "success", "success": true }