Add Policy - Apinizer Dokümantasyonu

Endpoint

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

Authentication

Requires a Personal API Access Token.

Authorization: Bearer YOUR_TOKEN

Request

Headers

Header	Value	Required
Authorization	Bearer	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
apiProxyName	string	Yes	API Proxy name
policyName	string	Yes	Policy name (must be unique within the API Proxy)

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"
      }
    ],
    "policyCondition": {
      "conditionRuleList": [
        {
          "conditionCriteria": "VALUE",
          "firstVariable": {
            "name": "userTypeHeader",
            "type": "HEADER",
            "headerName": "X-User-Type"
          },
          "variableDataType": "STRING",
          "valueComparisonOperator": "EQ",
          "secondValueSource": "VALUE",
          "secondValue": "PREMIUM"
        }
      ]
    }
  }
}

Request Body Fields

Policy Operation Metadata

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). If null or >= list size, policy is added at the end

EnumPolicyTargetScope

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

EnumPolicyTargetPipeline

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

EnumHttpRequestMethod

GET - GET method
POST - POST method
PUT - PUT method
DELETE - DELETE method
PATCH - PATCH method
OPTIONS - OPTIONS method
HEAD - HEAD method
TRACE - TRACE method
ALL - All methods

Note: When targetScope is ENDPOINT, both targetEndpoint and targetEndpointHTTPMethod are required.

policy

The policy object structure varies by policy type. All policies share common base fields:

Common Policy Fields

Field	Type	Required	Default	Description
type	string	Yes	-	Policy type (discriminator field)
description	string	No	-	Policy description
active	boolean	No	true	Whether policy is active
policyCondition	object	No	-	Policy condition configuration (see PolicyCondition below)
errorMessageList	array	No	-	Custom error messages (if not provided, standard messages are used)

Note: The name field is not included in the request body. The policy name is taken from the path parameter {policyName}.

Policy Types

Each policy type has its own specific fields. See individual policy documentation pages for details:

API Based Throttling
Blocked IP List
Allowed IP List
Authentication Basic
… (see Policies Index for complete list)

Policy Condition (PolicyConditionDTO)

Field	Type	Required	Default	Description
conditionRuleList	array	No	[]	List of condition rules. If empty, default AND condition is used

Note: If conditionRuleList is empty or not provided, a default AND condition is created.

conditionRuleList Item (ConditionRuleDTO)

Field	Type	Required	Default	Description
conditionRuleList	array	No	[]	Nested condition rules (for complex conditions)
conditionCriteria	string	Yes	-	Condition criteria: `VALUE`, `NOT`, `AND`, or `OR`
firstVariable	object	Yes	-	First variable for comparison (see VariableDTO below)
variableDataType	string	Yes	-	Variable data type: `STRING`, `NUMBER`, `DATE`, `BOOLEAN`
dateFormat	string	No	-	Date format for date comparisons (required if variableDataType=DATE)
valueComparisonOperator	string	Yes	-	Comparison operator (see EnumConditionValueComparisonOperator below)
secondValueSource	string	Yes	-	Second value source: `VALUE` or `VARIABLE`
secondValue	string	No*	-	Second value for comparison (required if secondValueSource=VALUE)
secondVariable	object	No*	-	Second variable for comparison (required if secondValueSource=VARIABLE)

EnumConditionCriteria

VALUE - Value comparison
NOT - Negation
AND - Logical AND
OR - Logical OR

EnumConditionVariableDataType

STRING - String type
NUMERIC - Numeric type
DATE - Date type

EnumConditionValueComparisonOperator

LT - Less than
LE - Less than or equal to
GT - Greater than
GE - Greater than or equal to
EQ - Equal to
NE - Not equal to
STARTS_WITH - Starts with
ENDS_WITH - Ends with
CONTAINS - Contains
NOT_CONTAINS - Does not contain
IS_EMPTY - Exists and is empty
IS_NOT_EMPTY - Exists and is not empty
IS_EXISTS - Exists
IS_NOT_EXISTS - Does not exist
IN - In list
NOT_IN - Not in list

EnumConditionValueSource

VALUE - Compare with a constant value
VARIABLE - Compare with another variable

firstVariable / secondVariable (VariableDTO)

Field	Type	Required	Default	Description
id	string	No	-	Variable ID (if referencing existing variable)
projectId	string	No	-	Project ID (if referencing existing variable)
name	string	No*	-	Variable name (required if id not provided)
description	string	No	-	Variable description
type	string	Yes	-	Variable type: `HEADER`, `PARAMETER`, `BODY`, `CONTEXT_VALUES`, `CUSTOM`
headerName	string	No*	-	Header name (required if type=HEADER)
paramType	string	No*	-	Parameter type: `QUERY`, `PATH`, `FORM` (required if type=PARAMETER)
paramName	string	No*	-	Parameter name (required if type=PARAMETER)
paramPath	string	No	-	Parameter path
formName	string	No	-	Form name (for form parameters)
xpathValue	string	No*	-	XPath value (required if type=BODY and content is XML)
jsonPathValue	string	No*	-	JSONPath value (required if type=BODY and content is JSON)
messageContentType	string	No*	-	Message content type: `JSON`, `XML`, `FORM` (required if type=BODY)
contextValue	string	No*	-	Context value (required if type=CONTEXT_VALUES)
zoneId	string	No	-	Zone ID (for date context values)
initWithScript	boolean	No	false	Initialize with script
scriptLanguage	string	No	-	Script language: `GROOVY`, `JAVASCRIPT` (required if initWithScript=true)
scriptBody	string	No	-	Script body (required if initWithScript=true)

EnumVariableType

HEADER - HTTP header
PARAMETER - Query/path/form parameter
BODY - Request/response body
CONTEXT_VALUES - Context values (e.g., current time, IP address)
CUSTOM - Custom variable (script-based)

EnumVariableParameterType

QUERY - Query parameter
PATH - Path parameter
FORM - Form parameter

EnumMessageContentType

JSON - JSON content
XML - XML content
FORM - Form content

EnumVariableContextValue

CURRENT_TIME - Current timestamp
CURRENT_DATE - Current date
CLIENT_IP - Client IP address
CLIENT_PORT - Client port
SERVER_IP - Server IP address
SERVER_PORT - Server port
REQUEST_METHOD - HTTP request method
REQUEST_URI - Request URI
REQUEST_PATH - Request path
REQUEST_QUERY_STRING - Query string
REQUEST_PROTOCOL - Request protocol
REQUEST_HOST - Request host
REQUEST_SCHEME - Request scheme
RESPONSE_STATUS_CODE - Response status code
RESPONSE_STATUS_TEXT - Response status text
API_PROXY_NAME - API Proxy name
API_PROXY_ID - API Proxy ID
ENDPOINT_NAME - Endpoint name
ENDPOINT_ID - Endpoint ID
ENVIRONMENT_NAME - Environment name
ENVIRONMENT_ID - Environment ID
PROJECT_NAME - Project name
PROJECT_ID - Project ID
USER_NAME - User name
USER_ID - User ID
ORGANIZATION_NAME - Organization name
ORGANIZATION_ID - Organization ID
ZONE_ID - Zone ID
TIMEZONE_ID - Timezone ID

EnumScriptType

GROOVY - Groovy script
JAVASCRIPT - JavaScript script

Response

Success Response (200 OK)

{
  "status": "SUCCESS"
}

If deploy: true is set in the request, the response includes deployment result:

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true,
    "responseTime": 1500,
    "detailList": [
      {
        "envName": "production",
        "podName": "pod-123",
        "podIp": "10.0.0.1",
        "success": true,
        "responseTime": 1500
      }
    ]
  }
}

Response Fields

Field	Type	Description
status	string	Response status: `SUCCESS` or `FAILURE`
deploymentResult	object	Deployment result (if deploy=true). See Deployment Result Object

Deployment Result Object (deploymentResult)

Field	Type	Description
success	boolean	Overall deployment success status
responseTime	integer	Total deployment response time in milliseconds
detailList	array	List of deployment details per pod/environment

Deployment Detail Object (detailList item)

Field	Type	Description
envName	string	Environment name
podName	string	Pod name where deployment occurred
podIp	string	Pod IP address
success	boolean	Deployment success status for this pod
responseTime	integer	Deployment response time for this pod in milliseconds

EnumStatus

SUCCESS - Operation successful
FAILURE - Operation failed

Error Response (400 Bad Request)

{
  "error": "bad_request",
  "error_description": "A policy with same name (my-policy) is already exist in API Proxy!"
}

Common Causes

Policy name already exists
Invalid targetScope (ENDPOINT without targetEndpoint)
Invalid targetEndpoint (endpoint not found in API Proxy)
Invalid policy type
Missing required policy fields
Invalid condition configuration

Error Response (401 Unauthorized)

{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}

Error Response (404 Not Found)

{
  "error": "not_found",
  "error_description": "ApiProxy (name: MyAPI) was not found!"
}

cURL Example

Example 1: Add Policy to All Endpoints

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": "Throttling policy",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 100,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'

Example 2: Add Policy to Specific Endpoint

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/endpoint-throttling/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ENDPOINT",
      "targetEndpoint": "/api/users",
      "targetEndpointHTTPMethod": "GET",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 2
    },
    "policy": {
      "type": "policy-api-based-throttling",
      "description": "Endpoint-specific throttling",
      "active": true,
      "targetVariableForIdentity": {
        "type": "HEADER",
        "headerName": "X-API-Key"
      },
      "messageCountForInterval": 50,
      "throttlingInterval": "ONE_MINUTE",
      "intervalPeriodLength": 1,
      "intervalWindowType": "FIXED"
    }
  }'

Example 3: Add Policy with Condition

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/conditional-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 1
    },
    "policy": {
      "type": "policy-black-ip",
      "description": "Block IPs for VIP users",
      "active": true,
      "ipList": ["192.168.1.100"],
      "policyCondition": {
        "conditionRuleList": [
          {
            "conditionCriteria": "VALUE",
            "firstVariable": {
              "name": "userTypeHeader",
              "type": "HEADER",
              "headerName": "X-User-Type"
            },
            "variableDataType": "STRING",
            "valueComparisonOperator": "EQ",
            "secondValueSource": "VALUE",
            "secondValue": "PREMIUM"
          }
        ]
      }
    }
  }'

Permissions

User must have API_MANAGEMENT + MANAGE permission in the project
If deploy: true is set in the request, user must also have API_MANAGEMENT + DEPLOY_UNDEPLOY permission

Notes and Warnings

Policy Name: Policy name is taken from the path parameter, not from the request body. The name field in PolicyDTO is ignored (marked with @JsonIgnore).
Unique Names: Policy names must be unique within the API Proxy
Order: Order starts from 1. If order is null or >= current policy list size, policy is added at the end
Deployment: If deploy: true, ensure environments exist and user has deployment permissions
Conditions: If policyCondition is not provided, a default AND condition is created
Error Messages: If errorMessageList is not provided, standard error messages are used
Endpoint Scope: When using targetScope: ENDPOINT, ensure the endpoint exists in the API Proxy
Variable References: Variables can be referenced by id (if existing) or defined inline

List Policies - List all policies
Update Policy - Update an existing policy
Delete Policy - Delete a policy
Policy API Based Throttling - Example policy documentation

Home

​Endpoint

​Authentication

​Header

​Request

​Headers

​Path Parameters

​Request Body

​Full JSON Body Example

​Request Body Fields

Policy Operation Metadata

​EnumPolicyTargetScope

​EnumPolicyTargetPipeline

​EnumHttpRequestMethod

policy

Common Policy Fields

Policy Types

Policy Condition (PolicyConditionDTO)

conditionRuleList Item (ConditionRuleDTO)

​EnumConditionCriteria

​EnumConditionVariableDataType

​EnumConditionValueComparisonOperator

​EnumConditionValueSource

firstVariable / secondVariable (VariableDTO)

​EnumVariableType

​EnumVariableParameterType

​EnumMessageContentType

​EnumVariableContextValue

​EnumScriptType

​Response

​Success Response (200 OK)

​Response Fields

​Deployment Result Object (deploymentResult)

​Deployment Detail Object (detailList item)

​EnumStatus

​Error Response (400 Bad Request)

​Common Causes

​Error Response (401 Unauthorized)

​Error Response (404 Not Found)

​cURL Example

​Example 1: Add Policy to All Endpoints

​Example 2: Add Policy to Specific Endpoint

​Example 3: Add Policy with Condition

​Permissions

​Notes and Warnings

​Related Documentation