Skip to Main
View .mdAsk ClaudeAsk ChatGPT

Without caching, every page view that renders API data makes a live HTTP request — slow for site visitors and wasteful against rate limits. HuxxConnect caches responses per endpoint with a cache duration you control, and can keep serving the last good response when the API goes down.

Quick version:

  1. Endpoint editor → Cache TTL (seconds): e.g. 300. 0 disables caching (the default). Only GET responses are cached.
  2. Optional: Stale Cache Grace Period (seconds) (appears when TTL > 0) — on API failure, the last successful response is served if it is within this window. A global default lives in Settings (recommended: 3600).
  3. Per-request override in PHP: 'cache' => 300 or 'cache' => false in the args array.
  4. Clear: per-endpoint button in the endpoint list, Clear Cache on the API screen, or Clear All Cache in Settings → Cache.

Set the cache duration

Edit the endpoint and set Cache TTL (seconds) — how long a response is reused before the next live request. 0 (the default) disables caching for the endpoint. Successful GET responses are stored for that many seconds; POST, PUT, PATCH, and DELETE responses are never cached, regardless of the setting.

Cache entries are keyed by the full request — URL, headers, and body — so ?limit=2 and ?limit=5 are cached independently, as are requests with different path variable values. Credential headers (Authorization, X-Api-Key, Cookie) are excluded from the key, so rotating a token does not fragment the cache. Storage auto-detects your site: a persistent object cache (Redis, Memcached) when one is active, WordPress transients otherwise (src/Plugin.php).

New to APIs? Read this first

A cache keeps a copy of the last answer so repeat questions don’t travel to the remote server. TTL — time to live — is how many seconds that copy stays valid. See How HuxxConnect works.

Serve stale data when the API fails

The stale-cache fallback keeps your pages populated through an outage. When enabled, every successful response is stored a second time with a longer TTL — the grace period. If a later live request fails, HuxxConnect serves that stale copy instead of an error, as long as it is still inside the window (src/Core/Executor.php).

Two places to set it:

  • Globally — Settings → General → Stale Cache Grace Period (seconds). Its help text: “0 = disabled (default). Recommended: 3600 (1 hour).” Maximum 86400 (one day).
  • Per endpoint — the Stale Cache Grace Period (seconds) field that appears under Cache TTL once caching is on. A non-zero value here overrides the global setting for that endpoint.

The window counts from the last successful response, so set it comfortably longer than the cache TTL — a 300-second TTL with a 3600-second grace period means an outage can start any time in that hour and visitors still see data. The fallback only applies to endpoints with caching enabled, and only after at least one successful response has been stored.

Override caching per request

The PHP argument cache overrides the endpoint’s TTL for a single request — an integer for a different duration, or false to bypass the cache entirely:

// Cache this request for 10 minutes regardless of the endpoint setting.
$data = huxx_api( 'demo_api', 'get_products', array( 'cache' => 600 ) );

// Always fetch live.
$fresh = huxx_api( 'demo_api', 'get_products', array( 'cache' => false ) );

echo count( $fresh['products'] );

Output:

30

There is no shortcode attribute for this — shortcodes always use the endpoint’s configured TTL. An override of 'cache' => 600 on a non-GET endpoint still caches nothing; the GET-only rule is absolute.

Clear cached responses

Three scopes, narrowest first:

  • One endpoint — in the API screen’s endpoint list, a clear-cache button appears on each endpoint whose Cache TTL is above 0 (tooltip: “Clear endpoint cache”).
  • One API — the Clear Cache button in the API screen’s header flushes every endpoint of that API.
  • Everything — Settings → Cache → Clear All Cache (“Clear all cached API responses.”).

Clearing also removes the stale-fallback copies in that scope. Editing and saving an endpoint does not clear its existing cache — after changing parameters, clear the endpoint’s cache so the next request rebuilds from the new configuration.

Advanced

Developers can adjust caching without touching the UI: the huxx_connect/cache/ttl and huxx_connect/cache/stale_ttl filters modify durations per API/endpoint, and huxx_connect/cache/should_cache can veto storage of specific responses (for example, refuse to cache an empty result set). The huxx_connect/cache/stale_fallback action fires whenever stale data is served, which makes a good alerting hook for outages.

If it didn’t work

Responses are never cached. Check the method — only GET is cached — and that Cache TTL is above 0. Then watch the request log via Debug API requests: cache hits skip the HTTP request and produce no log entry, so a fresh log row for every page view means the cache is not engaging.

The API went down and visitors saw errors anyway. The grace period was 0 (disabled) at both the endpoint and global level, the last successful response was older than the window, or the endpoint had never succeeded since its stale copy was last cleared. Set the endpoint’s grace period well above its TTL.

You changed the endpoint but keep seeing old data. The previous response is still within its TTL — saving an endpoint does not flush its cache. Use the endpoint’s clear-cache button and request again.