Add Policy

Overview

Adds a new policy to an API Proxy. The policy can be added to the request, response, or error pipeline, and can apply to all endpoints or a specific endpoint.

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 {token} 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:

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 Messages

See Error Response 400 Bad Request and Common Causes above for details.

Note: For detailed error response documentation, see Error Response (400 Bad Request) section above.

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"
          }
        ]
      }
    }
  }'

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