Update Policy

Overview

Updates an existing policy in an API Proxy. The policy can be updated with new configuration, moved to a different position in the pipeline, or moved to a different scope/pipeline.

Endpoint

PUT /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 exist)

Request Body

Full JSON Body Example

{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 2
  },
  "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"
      }
    ],
    "policyCondition": {
      "conditionRuleList": [
        {
          "conditionCriteria": "VALUE",
          "firstVariable": {
            "name": "userTypeHeader",
            "type": "HEADER",
            "headerName": "X-User-Type"
          },
          "variableDataType": "STRING",
          "valueComparisonOperator": "EQ",
          "secondValueSource": "VALUE",
          "secondValue": "PREMIUM"
        }
      ]
    }
  }
}

Request Body Fields

The request body structure is identical to Add Policy. See that documentation for complete field descriptions.

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 updating policy
deployTargetEnvironmentNameList array No [] List of environment names to deploy to
order integer No null Policy execution order (starts from 1). If null, keeps existing order. If >= list size, moves to end

Note: If order is null, the policy keeps its existing position. If order is provided, the policy is moved to that position.

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, POST, PUT, DELETE, PATCH, OPTIONS, HEAD, TRACE, ALL
policy

The policy object structure is identical to Add Policy. All policy fields can be updated.

Important: The policy type cannot be changed. If you need a different policy type, delete the existing policy and create a new one.

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 name (my-policy) does not exist in API Proxy!"
}

Common Causes

  • Policy name does not exist
  • Invalid targetScope (ENDPOINT without targetEndpoint)
  • Invalid targetEndpoint (endpoint not found in API Proxy)
  • Invalid policy type (cannot change policy type)
  • Missing required policy fields
  • Invalid condition configuration
  • Invalid order value (order < 1)

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: Update Policy Configuration

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

Example 2: Update Policy Order

Move a policy to a different position in the pipeline.

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": false,
      "order": 3
    },
    "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 3: Update Policy Scope

Move a policy from ALL endpoints to a specific endpoint.

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": "ENDPOINT",
      "targetEndpoint": "/api/users",
      "targetEndpointHTTPMethod": "GET",
      "targetPipeline": "REQUEST",
      "deploy": false,
      "order": 1
    },
    "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 4: Update Policy Pipeline

Move a policy from REQUEST pipeline to RESPONSE pipeline.

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/logging-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "RESPONSE",
      "deploy": false,
      "order": 1
    },
    "policy": {
      "type": "policy-script",
      "description": "Response logging",
      "active": true,
      "scriptLanguage": "GROOVY",
      "scriptBody": "log.info('Response: ' + response.statusCode)"
    }
  }'

Notes and Warnings

  • Policy Name: Policy name cannot be changed. Use Delete and Add to rename a policy.
  • Policy Type: Policy type cannot be changed. Use Delete and Add to change policy type.
  • Order: If order is null, the policy keeps its existing position. If order is provided, the policy is moved to that position (1-based indexing).
  • Scope Change: You can change targetScope from ALL to ENDPOINT or vice versa. Ensure the endpoint exists if using ENDPOINT scope.
  • Pipeline Change: You can change targetPipeline (REQUEST, RESPONSE, ERROR). The policy will be moved to the new pipeline.
  • Deployment: If deploy: true, ensure environments exist and user has deployment permissions.
  • Validation: All policy-specific validations apply. See individual policy documentation for required fields.