Edge Caching

EdgeWrap caches GET responses globally and serves them directly from edge nodes without hitting your origin. Configure caching defaults and per-path cache policies.

Dashboard Setup & Configuration

You can configure edge cache settings directly inside the EdgeWrap Dashboard:

Navigate to your project in the dashboard at https://app.edgewrap.pro.
Go to the Performance page and select the Edge Caching tab.
Toggle the Caching switch to Enabled.
Configure default caching variables: default Time-To-Live (TTL), stale-while-revalidate duration, and vary header rules.
Under Cache Rules, click Add Cache Rule to define custom caching rules or cache bypasses for specific paths.

API Configuration

Alternatively, you can manage your Edge Caching policies programmatically:

Enable caching on your project via API

curl -X PATCH https://server.edgewrap.pro/v1/projects/prj_01jxyz \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "cacheEnabled": true }'

200Success

{
  "success": true,
  "data": {
    "id": "prj_01jxyz",
    "cacheEnabled": true
  }
}

Configure Cache Settings

Set the default TTL, stale strategies, and which request properties are included in the cache key.

Param	Type	Required	Description
defaultTtlSec	integer (0–86400)	optional	How long to cache responses in seconds(default: 300)
maxTtlSec	integer	optional	Maximum TTL allowed (per-path rules cannot exceed this)(default: 86400)
staleWhileRevalidateSec	integer	optional	Serve stale content while fetching a fresh response from origin in the background. Eliminates cache-miss latency.(default: 60)
staleIfErrorSec	integer	optional	Serve stale content when origin returns an error or is unreachable. Keeps your API up during origin outages.(default: 3600)
varyByHeaders	string[]	optional	Include these request headers in the cache key (e.g. ['Accept-Language'] to cache per-language)
varyByQueryParams	string[]	optional	Only include these query params in the cache key (empty = include all)
varyByCookies	string[]	optional	Include these cookies in the cache key

Configure cache settings via API

curl -X PATCH https://server.edgewrap.pro/v1/projects/prj_01jxyz/cache/config \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultTtlSec": 300,
    "staleWhileRevalidateSec": 60,
    "staleIfErrorSec": 3600,
    "varyByHeaders": ["Accept-Language"],
    "varyByQueryParams": ["sort", "filter", "page"]
  }'

200Success

{
  "success": true,
  "data": {
    "projectId": "prj_01jxyz",
    "defaultTtlSec": 300,
    "staleWhileRevalidateSec": 60,
    "staleIfErrorSec": 3600,
    "varyByHeaders": [
      "Accept-Language"
    ],
    "varyByQueryParams": [
      "sort",
      "filter",
      "page"
    ]
  }
}

Set Per-Path Cache Rules

Override the default TTL for specific paths. The first matching rule wins, evaluated in priority order.

Param	Type	Required	Description
pathPattern	string	required	Glob pattern to match the request path (e.g. /api/products/*)
ttlSec	integer	required	TTL in seconds. Set to 0 to bypass the cache for this path.
bypassCache	boolean	optional	Skip cache lookup and write for this path(default: false)
priority	integer	optional	Rule order (lower = higher priority)(default: 100)

Bypass cache for user data

curl -X POST https://server.edgewrap.pro/v1/projects/prj_01jxyz/cache/rules \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pathPattern": "/api/user/*",
    "ttlSec": 0,
    "bypassCache": true,
    "priority": 5
  }'

Verify Cache Is Working

Every response from EdgeWrap includes an X-Cache-Status header showing the cache outcome for that request.

# First request — cache miss, fetches from origin
curl -i https://your-project.edgewrap.pro/api/products \
  -H "x-api-key: ek_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Look for this in the response headers:
# X-Cache-Status: MISS

# Second request — served from cache
curl -i https://your-project.edgewrap.pro/api/products \
  -H "x-api-key: ek_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# X-Cache-Status: HIT

Cache Status Values

X-Cache-Status	Meaning	Origin called?
HIT	Response served from cache.	No
MISS	Not in cache — fetched from origin and stored.	Yes
STALE	Stale cache served, refresh happening in background.	Yes (async)
BYPASS	Cache skipped (non-GET, bypassCache rule, or bypass header).	Yes

Tip: If you always see MISS, check your varyByHeaders config. Including headers like Authorization makes every request unique, preventing cache hits. Remove them from the vary config, or use bypassCache: true for authenticated endpoints.

Test Cache Key Resolution

Use the Cache Sandbox inside the dashboard to simulate request parameters and view exactly how EdgeWrap resolves the cache key:

Test cache key generation via API

curl -X POST https://server.edgewrap.pro/v1/projects/prj_01jxyz/cache/sandbox-call \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/products",
    "queryString": "sort=price",
    "headers": { "Accept-Language": "en-US" }
  }'