Controlling Akamai CDN Caching

When running Zuplo on Akamai Connected Cloud, your API Gateway can control how the Akamai CDN caches responses by setting the Cache-Control header. This allows you to optimize caching behavior for different endpoints without modifying Akamai Property Manager configurations.

How Akamai caching works

Akamai's CDN can cache responses at edge servers to reduce load to your Zuplo API Gateway and improve response times for clients.

When a request arrives, Akamai checks if a cached response exists. On a cache miss, the request goes to Zuplo, which can set cache headers on the response. Akamai caches the response according to those headers and serves subsequent requests directly from the edge cache.

The CDN determines caching behavior based on:

1. Akamai Property Manager settings - Default caching rules configured in your CDN property
2. Origin response headers - Headers sent by Zuplo that can override or influence default behavior

When your Akamai property is configured to "Honor origin Cache-Control and Expires" headers, Zuplo can control caching behavior on a per-response basis.

For complete details on Akamai's caching behavior, see the Akamai caching documentation.

Cache-Control header

The Cache-Control header controls caching for both the CDN and downstream clients (browsers). Akamai honors the following directives when configured to respect origin headers:

Using s-maxage for CDN caching

The s-maxage directive is specifically for shared caches like CDNs. When both max-age and s-maxage are present, Akamai uses s-maxage for edge caching and forwards max-age to browsers:

Code
Cache-Control: public, max-age=60, s-maxage=3600

This example caches content at the CDN for 1 hour while instructing browsers to cache for only 1 minute.

Common Cache-Control patterns

Setting cache headers in Zuplo

Using the Set Headers policy

The simplest way to add cache headers is using the Set Headers Outbound Policy:

config/policies.json
{
  "name": "cache-one-hour",
  "policyType": "set-headers-outbound",
  "handler": {
    "export": "SetHeadersOutboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "headers": [
        {
          "name": "Cache-Control",
          "value": "public, max-age=60, s-maxage=3600"
        }
      ]
    }
  }
}

This configuration caches responses at the CDN for 1 hour while allowing browsers to cache for only 1 minute.

Using custom code

For dynamic cache control based on response content or status, use a custom outbound policy:

modules/cache-control.ts
import { ZuploContext, ZuploRequest } from "@zuplo/runtime";

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
) {
  const headers = new Headers(response.headers);

  // Cache successful responses for 1 hour at CDN, 1 minute in browser
  if (response.status >= 200 && response.status < 300) {
    headers.set("Cache-Control", "public, max-age=60, s-maxage=3600");
  }
  // Don't cache error responses
  else if (response.status >= 400) {
    headers.set("Cache-Control", "no-store");
  }

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  });
}

Downstream cacheability

By default, Akamai sends the smaller of the origin's Cache-Control max-age and the remaining edge cache lifetime to clients. This ensures browsers don't cache content longer than it remains valid at the edge.

You can control downstream (client) caching independently using Property Manager settings or by setting explicit max-age values in your Cache-Control header.

For more information, see Akamai's downstream cacheability documentation.

Best practices

1. Use s-maxage for CDN caching - Separate CDN and browser cache durations for better control
2. Don't cache authenticated responses - Use private or no-store for user-specific data
3. Set appropriate Vary headers - If responses vary by header (like Accept-Language), include a Vary header

Akamai Property Manager configuration

For Zuplo to control caching via headers, ensure your Akamai CDN property is configured to honor origin headers:

1. In Property Manager, navigate to your property's caching behavior
2. Set Caching Option to "Honor origin Cache-Control and Expires"
3. Enable the Cache-Control directives you want to honor (max-age, s-maxage, etc.)
4. Set a Default Max-age as a fallback when origin headers are missing

For detailed CDN setup instructions, see Setting up Akamai CDNs.

Related resources

• Set Headers Policy - Add headers to responses
• Caching Policy - Zuplo's built-in response caching
• Akamai Caching Documentation - Complete Akamai caching reference