API warmers

APIs go cold exactly like web pages do. If a JSON response is expensive to build and is cached at your CDN or gateway, the first client after expiry pays the same penalty a website visitor would.

API warmers solve that. They are managed separately from website warmers, under Account → API Warmers, and have their own plan limits.

When to use one#

An API warmer is not useful for endpoints that are never cached, or that are unique per user and therefore have no shared cached copy to fill.

Creating an API warmer#

1. 1

   Verify the API hostname

   Endpoint URLs must use a verified hostname, exactly like website warmers. See Hostname verification.

2. 2

   Name the warmer and leave it inactive

   Configure first, activate when you are satisfied.

3. 3

   Add one or more endpoints

   Each endpoint has a URL and an HTTP method, and optionally a label, body, and content type.

4. 4

   Add auth if the endpoint needs it

   Global headers and cookies are applied to every request the warmer makes.

5. 5

   Optionally expand with a config matrix

   Cover many variants — locales, tenants, IDs — without creating dozens of near-identical warmers.

6. 6

   Set the rate and intervals, then activate

   Same idea as website warmers: warm often enough to beat your cache TTL, slowly enough not to hurt.

Endpoints#

Each endpoint in the warmer is configured independently:

Label

An optional human-readable name, so a long list of endpoints stays readable.

URL

The full endpoint address on a verified hostname. May contain path placeholders like {id} or :id when paired with a PATH dimension.

Method

GET, POST, and others depending on your plan. Plans typically allow GET and HEAD by default, with more methods on higher tiers.

Protocol

REST or GRAPHQL. Choosing GraphQL reveals the operation and query fields.

Request body template

The body to send, for methods that carry one. Requires the API request body entitlement.

Content-Type

The content type of the request body, typically application/json.

Idempotent

Marks the endpoint as safe to call twice, enabling the cold/warm double fetch that measures the improvement. Only enable it when calling twice genuinely has no side effects.

Enabled

Whether this specific endpoint is included in runs. Handy for temporarily disabling one endpoint without deleting it.

Config matrices#

Most APIs have variants: the same endpoint called per locale, per tenant, per currency, or per ID. Creating a warmer for each is unmaintainable.

A config matrix solves this. You define dimensions with multiple values, and Cache Rocket expands the full cartesian product into individual warm requests.

A worked example

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensions:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Expands to 6 warm requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

If you exceed the plan maximum, the warmer will not save. Reduce values, split across several warmers, or upgrade.

Authentication#

Global request headers and cookies are applied to every variant the warmer generates. This is where an Authorization header or a session cookie goes.

Authorization: Bearer YOUR_LONG_LIVED_TOKEN
X-Api-Key: YOUR_API_KEY

Tokens expire. If an API warmer suddenly starts returning 401, a hard-coded token is the first thing to check.

GraphQL#

GraphQL needs its own treatment because performance depends on the specific operation, not the endpoint path. Hitting /graphql once tells you nothing; warming your three heaviest queries tells you everything.

Set an endpoint's protocol to GraphQL, then supply:

• GraphQL operation — whether this is a query or a mutation. Warming mutations is almost never appropriate.
• GraphQL query — the operation document to send.
• Variables — supply them through the request body template, or as matrix dimension values to warm several variable sets.

OpenAPI import#

On supported plans you can import endpoints straight from an OpenAPI 3 specification instead of typing them in. Paste the URL of a JSON or YAML spec and click Import; discovered endpoints are added to the warmer, ready to prune and adjust.

Limits and scheduling#

Max warms per minute

Rate ceiling for this API warmer, equivalent to max URLs per minute on a website warmer.

Request timeout

How long to wait for a response before giving up.

Auto start interval

How often a new warm pass begins, in seconds.

Enqueue interval

Pacing of re-queued work within the cycle.

Rewrite to HTTPS

Upgrade http:// endpoint URLs to https://.

Warm schedule

Peak and off-peak windows, same JSON format as website warmers. See Advanced warming.

Your plan also caps the number of API warmers, endpoints per warmer, and combinations per warmer.

Common problems#

Everything returns 401 or 403.

The auth header or cookie is missing, wrong, or expired. Long-lived tokens are the usual culprit — check the token is still valid and has not rotated.

The warmer will not save, citing too many combinations.

Your matrix expands beyond the plan maximum. Reduce dimension values, split endpoints across several warmers, or upgrade.

The method I need is not in the dropdown.

Plans restrict which HTTP methods are allowed. Lower tiers typically permit only GET and HEAD.

Warming runs cleanly but responses are still slow for real clients.

You are probably filling a different cache variant than clients request — commonly because of an Authorization header, a cookie, or a header your CDN varies on. Compare the exact request a real client sends with what the warmer sends.

Can I warm an endpoint that requires a signed, short-lived token?

Not reliably, because the warmer cannot generate a fresh signature per run. Either expose a cacheable unauthenticated variant, or use a long-lived service token where that is safe.