Update Cache Settings

Endpoint

PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/settings/cache/

Authentication

Requires a Personal API Access Token.

Header

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

Request Body

Full JSON Body Example

{
  "cacheSettings": {
    "name": "Cache Settings",
    "description": "Cache configuration",
    "cacheActive": true,
    "cacheOnlyHttpGetRequests": true,
    "cacheKeyType": "QUERY_PARAMS",
    "cacheStorageType": "LOCAL",
    "capacity": 1000,
    "ttl": 3600,
    "handlingAction": "CONTINUE",
    "invalidationRequiresAuthn": false,
    "cacheNullValue": false,
    "variableList": []
  },
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}

Request Body Fields

Field	Type	Required	Default	Description
cacheSettings	object	Yes	-	Cache settings object (see fields below)
deploy	boolean	No	false	If true, deploy the API proxy after saving changes
deployTargetEnvironmentNameList	array[string]	No	-	List of environment names to deploy to (required when deploy=true)

cacheSettings Fields

Field	Type	Required	Default	Description
name	string	No	-	Cache settings name
description	string	No	-	Cache settings description
cacheActive	boolean	No	false	Enable/disable cache
cacheOnlyHttpGetRequests	boolean	No	true	Cache only GET requests (if false, caches all methods)
cacheKeyType	string	No	QUERY_PARAMS	Cache key type
cacheStorageType	string	No	DISTRIBUTED	Cache storage type
capacity	integer	No	-	Maximum cache capacity (number of entries)
ttl	integer	No	-	Time to live in seconds
handlingAction	string	No	-	Cache handling action when cache hit occurs
invalidationRequiresAuthn	boolean	No	false	Require authentication for cache invalidation
cacheNullValue	boolean	No	false	Cache null/empty responses
variableList	array	No	[]	List of variables for custom cache key (if cacheKeyType=CUSTOM)

Partial update behavior

This endpoint applies only the fields present in the request body. Omitting a field, or sending it as null, keeps the value that is currently stored — including a setting an operator deliberately turned off. To change a value you must send it explicitly; false, 0 and an empty string are explicit values, not omissions.

The Default column above applies only when the settings object is created for the first time. On a proxy that already has these settings, an omitted field keeps its stored value, not the default.

List fields are replaced as a whole: an omitted list keeps the stored list, and an explicitly empty list ([]) clears it.

Clients that read the settings and send the complete object back keep working unchanged; properties the endpoint does not recognise are ignored rather than rejected.

EnumCacheKeyType

• QUERY_PARAMS - Use query parameters as cache key
• CUSTOM - Use custom variables as cache key (requires variableList)

EnumCacheStorageType

• LOCAL - Local cache (per worker instance)
• DISTRIBUTED - Distributed cache (shared across all workers)

EnumCacheHandlingAction

• CONTINUE - Return cached response and continue to backend (for logging/monitoring)
• STOP - Return cached response and stop (do not call backend)

Variable Object (for variableList when cacheKeyType=CUSTOM)

{
  "name": "userId",
  "type": "HEADER",
  "dataType": "STRING"
}

EnumVariableType

• HEADER - Extract from HTTP header
• PARAMETER - Extract from query parameter
• BODY - Extract from request body
• CONTEXT_VALUES - Extract from context values
• CUSTOM - Custom variable

EnumConditionVariableDataType

• NUMERIC - Numeric value
• STRING - String value
• DATE - Date value

Response

Success Response (200 OK)

{
  "success": true
}

When deploy=true is specified:

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

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
deploymentResult	object	Deployment result details (only present when deploy=true)
deploymentResult.success	boolean	Whether the overall deployment was successful
deploymentResult.deploymentResults	array	List of per-environment deployment results

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "handlingAction is required"
}

Common Causes

• Missing required field handlingAction
• Invalid enum values
• Invalid cache configuration

Error Response (401 Unauthorized)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

Example 1: Basic Cache Configuration

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cacheSettings": {
      "name": "Cache Settings",
      "cacheActive": true,
      "cacheOnlyHttpGetRequests": true,
      "cacheKeyType": "QUERY_PARAMS",
      "cacheStorageType": "LOCAL",
      "capacity": 1000,
      "ttl": 3600,
      "handlingAction": "STOP",
      "cacheNullValue": false
    }
  }'

Example 2: Custom Cache Key

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cacheSettings": {
      "name": "Cache Settings",
      "cacheActive": true,
      "cacheKeyType": "CUSTOM",
      "cacheStorageType": "DISTRIBUTED",
      "capacity": 5000,
      "ttl": 7200,
      "handlingAction": "CONTINUE",
      "variableList": [
        {
          "name": "userId",
          "type": "HEADER",
          "dataType": "STRING"
        },
        {
          "name": "apiVersion",
          "type": "PARAMETER",
          "dataType": "STRING"
        }
      ]
    }
  }'

Example 3: Save and Deploy

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cacheSettings": {
      "name": "Cache Settings",
      "cacheActive": true,
      "cacheOnlyHttpGetRequests": true,
      "cacheKeyType": "QUERY_PARAMS",
      "cacheStorageType": "DISTRIBUTED",
      "capacity": 2000,
      "ttl": 1800,
      "handlingAction": "STOP",
      "cacheNullValue": false
    },
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"]
  }'

Example 4: Partial Update (Change One Field)

Only ttl is sent, so cacheActive, the cache key type and variableList keep the values stored on the proxy — a timeout change cannot silently re-enable or disable caching.

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/settings/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cacheSettings": {
      "ttl": 600
    }
  }'

Notes and Warnings

• handlingAction: Required field. CONTINUE allows backend call for logging, STOP prevents backend call
• Cache Key: When cacheKeyType=CUSTOM, provide variableList to define cache key components
• Storage Type: LOCAL cache is faster but not shared; DISTRIBUTED cache is shared across workers
• TTL: Cache entries expire after TTL seconds
• Capacity: Maximum number of cache entries (older entries are evicted when limit reached)
• GET Only: When cacheOnlyHttpGetRequests=true, only GET requests are cached (endpoint-level cache can override)
• Null Values: When cacheNullValue=false, null/empty responses are not cached
• Deploy: When deploy=true, the API proxy is automatically deployed to the specified environments after saving

Permissions

User must have API_MANAGEMENT + MANAGE permission in the project.

Related Documentation

• Update CORS Settings - Update CORS settings
• Get API Proxy - Get API proxy details