Update Endpoint Cache Settings

Endpoint

PATCH /apiops/projects/{projectName}/apiProxies/{apiProxyName}/endpoints/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

The request body includes endpoint identifier and CacheSettings structure. See Update Cache Settings for detailed cache settings field descriptions.

Full JSON Body Example - Basic Cache Configuration

{
  "identifierName": "/api/users",
  "identifierHttpMethod": "GET",
  "cacheSettings": {
    "name": "Endpoint Cache Settings",
    "description": "Cache configuration for this endpoint",
    "cacheActive": true,
    "cacheOnlyHttpGetRequests": false,
    "cacheKeyType": "QUERY_PARAMS",
    "cacheStorageType": "LOCAL",
    "capacity": 1000,
    "ttl": 3600,
    "handlingAction": "STOP",
    "invalidationRequiresAuthn": false,
    "cacheNullValue": false,
    "variableList": []
  },
  "deploy": false,
  "deployTargetEnvironmentNameList": []
}

Full JSON Body Example - Custom Cache Key

{
  "identifierName": "/api/users",
  "identifierHttpMethod": "GET",
  "cacheSettings": {
    "name": "Endpoint Cache with Custom Key",
    "description": "Cache using custom variables",
    "cacheActive": true,
    "cacheOnlyHttpGetRequests": false,
    "cacheKeyType": "CUSTOM",
    "cacheStorageType": "DISTRIBUTED",
    "capacity": 5000,
    "ttl": 7200,
    "handlingAction": "CONTINUE",
    "invalidationRequiresAuthn": true,
    "cacheNullValue": true,
    "variableList": [
      {
        "name": "userId",
        "type": "HEADER",
        "dataType": "STRING"
      },
      {
        "name": "apiVersion",
        "type": "PARAMETER",
        "dataType": "STRING"
      }
    ]
  }
}

Request Body Fields

Field	Type	Required	Default	Description
identifierName	string	Yes	-	Endpoint path/name (used to identify the endpoint)
identifierHttpMethod	string	Yes	-	HTTP method for the endpoint (used to identify the endpoint). See EnumHttpRequestMethod
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)

Cache Settings Object Fields

Field	Type	Required	Default	Description
name	string	Yes	-	Cache settings name
description	string	No	-	Cache settings description
cacheActive	boolean	No	false	Enable/disable cache for this endpoint
cacheOnlyHttpGetRequests	boolean	No	true	Cache only GET requests (if false, caches all methods)
cacheKeyType	string	No	QUERY_PARAMS	Cache key type. See EnumCacheKeyType
cacheStorageType	string	No	DISTRIBUTED	Cache storage type. See EnumCacheStorageType
capacity	integer	No	-	Maximum cache capacity (number of entries)
ttl	integer	No	-	Time to live in seconds
handlingAction	string	Yes	-	Cache handling action when cache hit occurs. See EnumCacheHandlingAction
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). See Variable Definition

EnumCacheKeyType (cacheKeyType)

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

EnumCacheStorageType (cacheStorageType)

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

EnumCacheHandlingAction (handlingAction)

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

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 (only present when deploy=true)
deploymentResult.success	boolean	Whether the overall deployment was successful
deploymentResult.deploymentResults	array	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
• Invalid variableList when cacheKeyType=CUSTOM

Error Response (401 Unauthorized)

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

cURL Example

Example 1: Basic Endpoint Cache Configuration

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

Example 2: Custom Cache Key with Variables

curl -X PATCH \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/endpoints/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifierName": "/api/users",
    "identifierHttpMethod": "GET",
    "cacheSettings": {
      "name": "Endpoint Cache with Custom Key",
      "cacheActive": true,
      "cacheKeyType": "CUSTOM",
      "cacheStorageType": "DISTRIBUTED",
      "capacity": 5000,
      "ttl": 7200,
      "handlingAction": "CONTINUE",
      "invalidationRequiresAuthn": true,
      "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/endpoints/cache/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifierName": "/api/users",
    "identifierHttpMethod": "GET",
    "cacheSettings": {
      "name": "Endpoint Cache Settings",
      "cacheActive": true,
      "cacheKeyType": "QUERY_PARAMS",
      "cacheStorageType": "LOCAL",
      "capacity": 1000,
      "ttl": 3600,
      "handlingAction": "STOP"
    },
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"]
  }'

Notes and Warnings

• Endpoint-Level Override:
  • Endpoint cache settings override API Proxy-level cache settings
  • If endpoint cache is disabled, API Proxy-level cache still applies
• handlingAction:
  • Required field
  • CONTINUE - Returns cached response but still calls backend (useful for logging/monitoring)
  • STOP - Returns cached response without calling backend (better performance)
• Cache Key:
  • When cacheKeyType=CUSTOM, provide variableList to define cache key components
  • Variables are combined to create unique cache keys
• Storage Type:
  • LOCAL cache is faster but not shared across workers
  • DISTRIBUTED cache is shared across all workers (recommended for multi-instance deployments)
• TTL:
  • Cache entries expire after TTL seconds
  • Set appropriate TTL based on data freshness requirements
• Capacity:
  • Maximum number of cache entries
  • Older entries are evicted when limit is reached (LRU eviction)
• GET Only:
  • When cacheOnlyHttpGetRequests=true, only GET requests are cached
  • When cacheOnlyHttpGetRequests=false, all HTTP methods can be cached (use with caution)
• Null Values:
  • When cacheNullValue=false, null/empty responses are not cached
  • When cacheNullValue=true, null/empty responses are cached (may cache error responses)
• Endpoint Validation:
  • Endpoint must exist in the API Proxy
  • Endpoint is identified by identifierName and identifierHttpMethod combination (not by ID)
• 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 Cache Settings - Update API Proxy-level cache settings
• Get Endpoint - Get endpoint details
• List Endpoints - List all endpoints
• Update Endpoint - Update endpoint configuration