Update Endpoint Cache Settings

Updates cache settings for a specific endpoint/method. Endpoint-level cache settings override API Proxy-level cache settings for the specific endpoint.

​

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	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)

{
  "error": "bad_request",
  "error_description": "handlingAction is required"
}

​

Common Causes

• Missing required field handlingAction
• Invalid enum values
• Invalid cache configuration
• Invalid variableList when cacheKeyType=CUSTOM

​

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!"
}

or

{
  "error": "not_found",
  "error_description": "Endpoint with name (/api/users) and HTTP method (GET) is not found!"
}

​

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