API Based Throttling Policy

General Information

Policy Type

policy-api-based-throttling

Endpoints

List Policies

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Add Policy

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Update Policy

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Delete Policy

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

---

List Policies

Endpoint

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Request

Headers

Header	Value
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name

Response

Success Response (200 OK)

{
  "success": true,
  "resultList": [
    {
      "apiProxy": {
        "name": "MyAPI",
        "requestPolicyList": [
          {
            "type": "policy-api-based-throttling",
            "name": "throttling-policy",
            "description": "API throttling policy",
            "active": true,
            "targetVariableForIdentity": {
              "type": "HEADER",
              "headerName": "X-API-Key"
            },
            "messageCountForInterval": 100,
            "throttlingInterval": "ONE_MINUTE",
            "intervalPeriodLength": 1,
            "intervalWindowType": "FIXED",
            "cacheConnectionTimeoutInSeconds": 3,
            "cacheErrorHandlingType": "FAIL",
            "showRateLimitStatisticsInResponseHeader": false
          }
        ],
        "responsePolicyList": [],
        "errorPolicyList": []
      }
    }
  ],
  "resultCount": 1
}

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/" \
  -H "Authorization: Bearer YOUR_TOKEN"

---

Add Policy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name

Request Body

Full JSON Body Example

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "API throttling policy - 100 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 100,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 3,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 1000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_MINUTE"
      }
    ]
  }
}

Request Body Fields

operationMetadata

Field	Type	Required	Default	Description
targetScope	string	Yes	-	Policy scope: ALL or ENDPOINT
targetEndpoint	string	No*	-	Endpoint path (required if targetScope=ENDPOINT)
targetEndpointHTTPMethod	string	No*	-	HTTP method (required if targetScope=ENDPOINT)
targetPipeline	string	Yes	-	Pipeline: REQUEST, RESPONSE, or ERROR
deploy	boolean	No	true	Whether to deploy after adding policy
deployTargetEnvironmentNameList	array	No	[]	List of environment names to deploy to
order	integer	No	null	Policy execution order (starts from 1)

Enum: targetScope

• ALL - Policy applies to all endpoints
• ENDPOINT - Policy applies only to specified endpoint

Enum: targetPipeline

• REQUEST - Executes in request pipeline
• RESPONSE - Executes in response pipeline
• ERROR - Executes in error pipeline

Enum: targetEndpointHTTPMethod

• GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD

policy

Field	Type	Required	Default	Description
type	string	Yes	-	Policy type: policy-api-based-throttling
description	string	No	-	Policy description
active	boolean	No	true	Whether policy is active
targetVariableForIdentity	object	Yes	-	Variable to identify clients for throttling
messageCountForInterval	integer	Yes	-	Maximum number of requests allowed in interval
throttlingInterval	string	Yes	-	Time interval for throttling
intervalPeriodLength	integer	No	1	Period length multiplier
intervalWindowType	string	No	FIXED	Window type: FIXED or SLIDING
cacheConnectionTimeoutInSeconds	integer	No	3	Cache connection timeout
cacheErrorHandlingType	string	No	FAIL	Cache error handling: FAIL or ALLOW
showRateLimitStatisticsInResponseHeader	boolean	No	false	Show rate limit stats in response headers
detailList	array	No	[]	List of detail rules for specific values

Enum: throttlingInterval

• ONE_SECOND - 1 second
• ONE_MINUTE - 1 minute
• ONE_HOUR - 1 hour
• ONE_DAY - 1 day

Enum: intervalWindowType

• FIXED - Fixed time window
• SLIDING - Sliding time window

Enum: cacheErrorHandlingType

• FAIL - Fail request if cache error occurs
• ALLOW - Allow request if cache error occurs

targetVariableForIdentity

See Variable Definition for complete variable documentation.

Field	Type	Required	Description
name	string	Yes	Variable name (e.g., "client.ip", "request.header.X-API-Key")
type	string	Yes	Variable type. See Variable Types
headerName	string	No*	Header name (required if type=HEADER)
paramType	string	No*	Parameter type (required if type=PARAMETER). See EnumVariableParameterType
paramName	string	No*	Parameter name (required if type=PARAMETER)
paramPath	string	No*	Parameter path template (required if type=PARAMETER and paramType=PATH)
messageContentType	string	No*	Message content type (required if type=BODY). See EnumMessageContentType
xpathValue	string	No*	XPath expression (required if type=BODY and messageContentType=XML)
jsonPathValue	string	No*	JsonPath expression (required if type=BODY and messageContentType=JSON)
contextValue	string	No*	Context value (required if type=CONTEXT_VALUES). See EnumVariableContextValue
zoneId	string	No*	Time zone ID (required for date/time context values)
scriptLanguage	string	No*	Script language (required if type=CUSTOM)
scriptBody	string	No*	Script body (required if type=CUSTOM)

Variable Types

• HEADER - Extract from HTTP header
• PARAMETER - Extract from query/path/form parameter
• BODY - Extract from request body (XML, JSON, or raw)
• CONTEXT_VALUES - Extract from system context values (e.g., CLIENT_IP, REQUEST_URI)
• CUSTOM - Extract using custom script

Common Context Values

• REQUEST_REMOTE_ADDRESS - Client IP address
• REQUEST_REQUEST_URI - Request URI
• REQUEST_HTTP_METHOD - HTTP method
• REQUEST_USERNAME_KEY - Username or key

For complete list of context values, see EnumVariableContextValue.

detailList (Optional)

Field	Type	Required	Default	Description
targetValue	string	Yes	-	Target value to match (e.g., "VIP")
regexExpression	boolean	No	false	Whether targetValue is regex
messageCountForInterval	integer	Yes	-	Message count for this detail
intervalPeriodLength	integer	No	1	Period length multiplier
quotaInterval	string	Yes	-	Time interval for this detail

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "API throttling policy - 100 requests per minute",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 100,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED",
      "cacheConnectionTimeoutInSeconds": 3,
      "cacheErrorHandlingType": "FAIL",
      "showRateLimitStatisticsInResponseHeader": true
    }
  }'

---

Update Policy

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name

Request Body

Full JSON Body Example

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-api-based-throttling",
    "description": "Updated API throttling policy - 200 requests per minute",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 200,
    "throttlingInterval": "ONE_MINUTE",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 5,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 2000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_MINUTE"
      }
    ]
  }
}

Note: Request body structure is the same as Add Policy. All fields should be provided for update.

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Updated API throttling policy - 200 requests per minute",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 200,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED",
      "cacheConnectionTimeoutInSeconds": 5,
      "cacheErrorHandlingType": "FAIL",
      "showRateLimitStatisticsInResponseHeader": true
    }
  }'

---

Delete Policy

Endpoint

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name

Request Body

Full JSON Body Example

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": false
  }
}

Request Body Fields

operationMetadata

Field	Type	Required	Default	Description
targetScope	string	Yes	-	Policy scope: ALL or ENDPOINT
targetPipeline	string	Yes	-	Pipeline: REQUEST, RESPONSE, or ERROR
deploy	boolean	No	false	Whether to deploy after deletion

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": []
  }
}

cURL Example

curl -X DELETE \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/throttling-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false
    }
  }'

---

Notes and Warnings

• Cache Dependency: This policy requires a cache connection. Ensure cache is properly configured.

• Identity Variable: Choose the identity variable carefully. Common choices:

  • HEADER with API key header - For API key-based throttling
  • CONTEXT with CLIENT_IP - For IP-based throttling
  • PARAMETER with user ID - For user-based throttling

• Window Types:

  • FIXED - Fixed time windows (e.g., minute 1:00-1:59)
  • SLIDING - Sliding time windows (last 60 seconds from current time)

• Detail List: Use detailList to provide different limits for specific values (e.g., VIP users)

• Rate Limit Headers: When showRateLimitStatisticsInResponseHeader is true, response includes:

  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Remaining requests in current window
  • X-RateLimit-Reset - Time when limit resets

• Deployment: Policy changes require deployment to take effect. Set deploy: true or deploy manually.

Related Documentation

• List Policies - List all policies
• Add Policy - General policy addition guide
• Update Policy - General policy update guide
• Delete Policy - General policy deletion guide