Set up caching and purge content

You enable caching for a group, select a cache policy and invalidate cached content for a group or domain.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• An HTTP group, a cache policy and a cacheable origin response. Set CACHE_POLICY_ID to your policy identifier.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
CACHE_POLICY_ID	Returned resource identifier, or your selected scope identifier.
DOMAIN_ID	Returned resource identifier, or your selected scope identifier.
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'CACHE_POLICY_ID: ' CACHE_POLICY_ID
export CACHE_POLICY_ID

Steps

1. Inspect the policy before attaching it.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/cache-policies/$CACHE_POLICY_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get cache policy

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

2. Enable caching and its status header.

   python3 - <<'PYBODY' | \
   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary @-
   import json, os
   print(json.dumps({'doCaching': True, 'defaultCachePolicyId': int(os.environ['CACHE_POLICY_ID']), 'cacheStatusHeaderEnabled': True}))
   PYBODY

   API reference: Update an HTTP group configuration

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

3. Read back the group.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

4. Purge the entire group when you need a new cache namespace.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/purge-cache" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Invalidate cached objects for an HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1,
       "cacheCheckpoint": 1
     }
   }

5. Alternatively, purge one domain.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID/domains/$DOMAIN_ID/purge-cache" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Invalidate cached objects for an HTTP domain

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "domainId": 1,
       "cacheCheckpoint": 1
     }
   }

Verify

Request the same cacheable URL repeatedly. Inspect x-nglb-cache-status and compare origin observations. After a purge, confirm the next delivery uses current origin content once the checkpoint reaches the request path. A purge changes the namespace; it does not establish physical deletion of stored bytes.

Use your configured site domain in this traffic check:

curl --silent --show-error --include "https://example.com/"

Expected: the site behavior described above. The application response body and status depend on your origin and selected policies.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

Troubleshooting

Symptom	Cause	Fix
Response is not cached	Method, cookies, Authorization or response controls prevent caching	Check the request and origin cache controls.
Route ignores group cache settings	A route overrides the assignment	Read the effective route cache policy and doCaching.
Content remains old after purge	Wrong scope or checkpoint has not reached the request path	Check group/domain scope and repeat a controlled content check.

Limits and defaults

Setting	Limit or default
Group caching	Disabled by default
Query string mode	Default standard; standard, ignoreQueryString or noQueryString
Cache status header	Disabled by default
Rule priority	1 to 100000000
TTL fields	0 to 2147483647 seconds

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.
412	Inspect the returned error details.
500	The request encounters a server error.

Related API operations

• DELETE /cache-policies/{cachePolicyId}
• DELETE /cache-policies/{cachePolicyId}/request-rules/{requestRuleId}
• DELETE /cache-policies/{cachePolicyId}/response-rules/{responseRuleId}
• GET /cache-policies
• GET /cache-policies/{cachePolicyId}
• GET /cache-policies/{cachePolicyId}/request-rules
• GET /cache-policies/{cachePolicyId}/request-rules/{requestRuleId}
• GET /cache-policies/{cachePolicyId}/response-rules
• GET /cache-policies/{cachePolicyId}/response-rules/{responseRuleId}
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}
• PATCH /cache-policies/{cachePolicyId}
• PATCH /cache-policies/{cachePolicyId}/request-rules/{requestRuleId}
• PATCH /cache-policies/{cachePolicyId}/response-rules/{responseRuleId}
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}
• POST /cache-policies
• POST /cache-policies/{cachePolicyId}/request-rules
• POST /cache-policies/{cachePolicyId}/response-rules
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/domains/{domainId}/purge-cache
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/purge-cache
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/purge-cache

API reference

• Delete a cache policy

• Delete a cache policy request rule

• Delete a cache policy response rule

• List cache policies associated with your account

• Get cache policy

• Returns the ordered list of request rules for a cache policy

• Get cache policy request rule

• Returns the ordered list of response rules for a cache policy

• Get cache policy response rule

• Get HTTP group

• Update a cache policy

• Update a cache policy request rule, including order and cache actions

• Update a cache policy response rule,

• Update an HTTP group configuration

• Create a new reusable cache policy container

• Create an ordered request rule for a cache policy

• Create an ordered response rule for a cache policy

• Invalidate cached objects for an HTTP domain

• Invalidate cached objects for an HTTP group

• Invalidate cached objects for an HTTP route

• Groups and Routes

• Cache Policies

Need Help?

Contact your account manager or use the Balancer portal.