Update Endpoint Cache Settings - Apinizer Dokümantasyonu

Endpoint

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

Authentication

Requires a Personal API Access Token.

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": []
  }
}

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)

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
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful

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

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

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)

Permissions

User must have API_MANAGEMENT + MANAGE permission in the project.

Update Cache Settings - Update API Proxy-level cache settings
Get Endpoint - Get endpoint details
List Endpoints - List all endpoints
Update Endpoint - Update endpoint configuration

Home

​Endpoint

​Authentication

​Header

​Request

​Headers

​Path Parameters

​Request Body

​Full JSON Body Example - Basic Cache Configuration

​Full JSON Body Example - Custom Cache Key

​Request Body Fields

​Cache Settings Object Fields

​EnumCacheKeyType (cacheKeyType)

​EnumCacheStorageType (cacheStorageType)

​EnumCacheHandlingAction (handlingAction)

​Response

​Success Response (200 OK)

​Response Fields

​Error Response (400 Bad Request)

​Common Causes

​Error Response (401 Unauthorized)

​Error Response (404 Not Found)

​cURL Example

​Example 1: Basic Endpoint Cache Configuration

​Example 2: Custom Cache Key with Variables

​Notes and Warnings

​Permissions

​Related Documentation