Caching API Per-Environment Update FAQ

FAQs
1

Caching API Per-Environment Update FAQ

What’s changing

We’ve updated the Caching API to support per-environment management of scheduled refresh contexts. You can now update caching configurations for specific environments (e.g., “staging”) without affecting other environments (e.g., “production”).

Do I need to change anything?

No. This update is fully backward compatible:

  • If you use a single environment (default): No changes needed
  • If you use multiple environments: No changes needed - the API now behaves more safely

How did it work before?

Previously, POST /api/v1/caching/refresh-contexts replaced ALL scheduled refresh contexts for your workspace. This worked well for single-environment setups. For multi-environment setups, you needed to include all environments in every request to avoid overwriting them.

How does it work now?

Smart Replacement (enabled by default):

  • When you update contexts, only the environments being updated are replaced
  • Other environments remain untouched
  • Example: Updating “staging” contexts won’t affect “production” contexts

Master Reset:

  • To clear ALL contexts across ALL environments, send an empty list: { "scheduledRefreshContexts": [] }

Are there new endpoints?

Yes! You can now manage contexts per environment:

Method Endpoint Description
PUT /api/v1/caching/refresh-contexts/environments/{env} Replace contexts for a specific environment
GET /api/v1/caching/refresh-contexts/environments/{env} Get contexts for a specific environment
DELETE /api/v1/caching/refresh-contexts/environments/{env} Delete all contexts for a specific environment

Can I still use the global endpoint?

Yes. The existing POST /api/v1/caching/refresh-contexts endpoint works exactly as before, but now with smart replacement behavior - it only replaces contexts for the environments you’re updating.

Example: Updating a specific environment

Before (old behavior):

# This would DELETE all contexts (including production!)
# then create only staging contexts
POST /api/v1/caching/refresh-contexts
{
  "scheduledRefreshContexts": [
    { "environment": "staging", "securityContext": {...} }
  ]
}

After (smart replacement):

# This only replaces "staging" contexts
# Production contexts remain untouched
POST /api/v1/caching/refresh-contexts
{
  "scheduledRefreshContexts": [
    { "environment": "staging", "securityContext": {...} }
  ]
}

Or use the new environment-specific endpoint:

PUT /api/v1/caching/refresh-contexts/environments/staging
{
  "scheduledRefreshContexts": [
    { "securityContext": {...} }
  ]
}