API Based Quota Policy

General Information

Policy Type

policy-api-based-quota

UI Documentation

📖 For detailed information: [UI Documentation Link - Link will be added here]

Description

API Based Quota policy limits the total number of requests that can be made within a specified time interval (hour, day, or month). Unlike throttling which limits rate, quota limits the total count. It uses a variable (such as API key, user ID, or IP address) to identify and track quota usage for individual clients.

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-quota",
            "name": "quota-policy",
            "description": "API quota policy - 10000 requests per day",
            "active": true,
            "targetVariableForIdentity": {
              "type": "HEADER",
              "headerName": "X-API-Key"
            },
            "messageCountForInterval": 10000,
            "quotaInterval": "ONE_DAY",
            "intervalPeriodLength": 1,
            "intervalWindowType": "FIXED",
            "cacheConnectionTimeoutInSeconds": 3,
            "cacheErrorHandlingType": "FAIL",
            "showRateLimitStatisticsInResponseHeader": false,
            "detailList": []
          }
        ],
        "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-quota",
    "description": "API quota policy - 10000 requests per day",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 10000,
    "quotaInterval": "ONE_DAY",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 3,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 100000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_DAY"
      }
    ]
  }
}
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-quota
description string No - Policy description
active boolean No true Whether policy is active
targetVariableForIdentity object Yes - Variable to identify clients for quota tracking
messageCountForInterval integer Yes - Maximum number of requests allowed in interval
quotaInterval string Yes - Time interval for quota: ONE_HOUR, ONE_DAY, or ONE_MONTH
intervalPeriodLength integer No 1 Period length multiplier
intervalWindowType string No FIXED Window type: FIXED or SLIDING
cacheConnectionTimeoutInSeconds integer No 3 Cache connection timeout in seconds
cacheErrorHandlingType string No FAIL Cache error handling: FAIL or CONTINUE
showRateLimitStatisticsInResponseHeader boolean No false Show quota statistics in response headers
detailList array No [] List of detail rules for specific values

Enum: quotaInterval

  • ONE_HOUR - 1 hour quota window
  • ONE_DAY - 1 day quota window
  • ONE_MONTH - 1 month quota window

Enum: intervalWindowType

  • FIXED - Fixed time window (e.g., day 1: 00:00-23:59)
  • SLIDING - Sliding time window (last 24 hours from current time)

Enum: cacheErrorHandlingType

  • FAIL - Fail request if cache error occurs
  • CONTINUE - Continue request if cache error occurs (quota not enforced)
targetVariableForIdentity
Field Type Required Description
type string Yes Variable type: HEADER, PARAMETER, BODY, CONTEXT, SCRIPT
headerName string No* Header name (required if type=HEADER)
paramName string No* Parameter name (required if type=PARAMETER)
contextValue string No* Context value (required if type=CONTEXT)

type

  • HEADER - Extract from HTTP header
  • PARAMETER - Extract from query/path parameter
  • BODY - Extract from request body
  • CONTEXT - Extract from context (e.g., CLIENT_IP)
  • SCRIPT - Extract using script

contextValue

  • CLIENT_IP - Client IP address
  • REQUEST_URI - Request URI
  • REQUEST_METHOD - HTTP method
  • USER_AGENT - User agent string
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 pattern
messageCountForInterval integer Yes - Message count quota for this detail
intervalPeriodLength integer No 1 Period length multiplier
quotaInterval string Yes - Time interval for this detail: ONE_HOUR, ONE_DAY, or ONE_MONTH

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/quota-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-quota",
      "description": "API quota policy - 10000 requests per day",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 10000,
      "quotaInterval": "ONE_DAY",
      "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-quota",
    "description": "Updated API quota policy - 20000 requests per day",
    "active": true,
    "targetVariableForIdentity": {
      "type": "HEADER",
      "headerName": "X-API-Key"
    },
    "messageCountForInterval": 20000,
    "quotaInterval": "ONE_DAY",
    "intervalPeriodLength": 1,
    "intervalWindowType": "FIXED",
    "cacheConnectionTimeoutInSeconds": 5,
    "cacheErrorHandlingType": "FAIL",
    "showRateLimitStatisticsInResponseHeader": true,
    "detailList": [
      {
        "targetValue": "VIP",
        "regexExpression": false,
        "messageCountForInterval": 200000,
        "intervalPeriodLength": 1,
        "quotaInterval": "ONE_DAY"
      }
    ]
  }
}

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/quota-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-quota",
      "description": "Updated API quota policy - 20000 requests per day",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 20000,
      "quotaInterval": "ONE_DAY",
      "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 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/quota-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.
  • Quota vs Throttling:
    • Quota limits total count (e.g., 10,000 requests per day)
    • Throttling limits rate (e.g., 100 requests per minute)
  • Identity Variable: Choose the identity variable carefully. Common choices:
    • HEADER with API key header - For API key-based quota
    • CONTEXT with CLIENT_IP - For IP-based quota
    • PARAMETER with user ID - For user-based quota
  • Quota Intervals:
    • ONE_HOUR - Hourly quota (resets every hour)
    • ONE_DAY - Daily quota (resets every day)
    • ONE_MONTH - Monthly quota (resets every month)
  • Window Types:
    • FIXED - Fixed time windows (e.g., day 1: 00:00-23:59)
    • SLIDING - Sliding time windows (last 24 hours from current time)
  • Detail List: Use detailList to provide different quotas for specific values (e.g., VIP users)
  • Quota Statistics 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 quota resets
  • Cache Error Handling:
    • FAIL - Request fails if cache is unavailable (recommended for strict quota enforcement)
    • CONTINUE - Request continues if cache is unavailable (quota not enforced)
  • Deployment: Policy changes require deployment to take effect. Set deploy: true or deploy manually.