Update Configuration (Version 1.0)

This article explains the legacy version of Rate Limiting that underwent end-of-life on June 30, 2021. Our new version of WAF expands upon all of the capabilities offered by WAF (Legacy) and Rate Limiting (Legacy) with a simplified and centralized setup. Please upgrade to the latest version of WAF at your earliest convenience.

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.

  1. Call the Get Configuration (Version 1.0) endpoint to retrieve the entire configuration.
  2. Modify the response of the Get Configuration (Version 1.0) endpoint as needed.
  3. Set the request body of the Update Configuration (Version 1.0) endpoint to the data updated in step 2.

Request

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:

VariableA variable represents a value that must be replaced. A variable consists of either a URL segment (e.g., "0001" in /0001/) or a query string value (e.g., "3" in mediaTypes=3).

Description

AccountNumber

Required

Replace this variable with a customer account number. This account number may be found in the upper left-hand corner of the TCC.

Request Headers

This endpointIdentifies a request's connection point to our REST API service. only takes advantage of common request headers.

Request Body

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:

  • true: Disabled. This rule will not be used to rate limit site traffic.
  • false: Enabled. Traffic is being restricted according to the policy defined in the rule.

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:

  • Missing / Empty Array: If the keys property is not defined or set to an empty array, all requests will be treated as a single group for the purpose of rate limiting.
  • IP: Indicates that requests will be grouped by IP address. Each unique IP address is considered a separate group.
  • User_Agent: Indicates that requests will be grouped by a client's user agent. Each unique combination of IP address and user agent is considered a separate group.

duration_sec

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

num

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.

type

Required

String

limits array > action object

Indicates the type of action that will be applied to rate limited requests. Valid values are:

  • custom-response: A custom HTTP response will be sent to rate limited responses.
  • drop-request: Rate limited requests will be dropped.
  • redirect-302: Rate limited requests will be redirected via a 302 Found.
  • nop: Rate limited requests will only generate an alert.

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

Custom Response Only

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

Custom Response Only

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

Custom Response Only

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

Custom Response Only

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

Custom Response Only

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

Redirect Only

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:

  • True: Case-insensitive
  • False: Case-sensitive

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:

  • True: Does not match
  • False: Matches

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.

Learn more about match types.

Valid values:

  • EM: Requires that the request's attribute be set to one of the value(s) defined in the values property.
  • IPMATCH: Requires that the request's IP address either be contained by an IP block or be an exact match to an IP address defined in the values property.

    Only use IPMATCH with the REMOTE_ADDR match condition.

  • RX: Requires that the request's attribute be an exact match to the regular expression defined in the value property.

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

value

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:

  • True: Case-insensitive
  • False: Case-sensitive

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:

  • True: Does not match
  • False: Matches

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.

Learn more about match types.

Valid values:

  • EM: Indicates that request's hostname must be an exact match to one of the case-sensitive values specified in the values property.
  • GLOB: Indicates that the request's hostname must be an exact match to the wildcard pattern defined in the value property.

  • RX: Indicates that the request's hostname must be an exact match to the regular expression defined in the value property.

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:

  • True: Case-insensitive
  • False: Case-sensitive

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:

  • True: Does not match
  • False: Matches

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.

Learn more about match types.

Valid values:

  • EM: Indicates that request's URL path must be an exact match to one of the case-sensitive values specified in the values property.
  • GLOB: Indicates that the request's URL path must be an exact match to the wildcard pattern defined in the value property.
  • RX: Indicates that the request's URL path must be an exact match to the regular expression defined in the value property.

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.

Response

The response to the above request includes an HTTP status code, response headers, and a response body.

Status Code

A status code indicates whether the request was successfully performed.

Response Headers

The response for this endpoint only includes standard HTTP response headers.

View common response headers.

Response Body

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:

  • true: Indicates that the configuration was updated.
  • false: Indicates that an error took place.

Errors

The response body for an unsuccessful request will contain an error response that provides additional information.

View common error messages.

Sample Request and Response

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
}