Skip to main content

​
Overview

The High IQ API uses a multi-tier caching system that automatically classifies endpoints and applies appropriate cache strategies. Caching is handled at both the CDN (Vercel Edge) and browser levels using standard HTTP cache headers, ETags, and stale-while-revalidate directives.

​
Cache Tiers

Endpoints are automatically classified into one of eight endpoint types, each with its own caching strategy:
TypeTTLBrowser max-ageCDN s-maxageStale-While-RevalidateETag
Static24 hours24 hours7 days7 daysStrong
Catalog5 minutes5 minutes5 minutes15 minutesStrong
Detail1 hour1 hour24 hours3 daysStrong
Search1 minute1 minute1 minute5 minutesWeak
AI Generated10 minutes10 minutesPrivate30 minutesWeak
User Data1 minute0 (no browser cache)PrivateNoneWeak
Analytics30 seconds0 (no browser cache)PrivateNoneWeak
RealtimeNo cacheNo cacheNo cacheNoneNone

​
Endpoint Classification

The cache classifier uses URL pattern matching to determine the endpoint type. Only GET requests are cached. All other HTTP methods (POST, PUT, DELETE, etc.) bypass the cache entirely.
Rarely-changing content:
/                    → Static (24h TTL)

​
Cache-Control Headers

The API builds Cache-Control headers dynamically based on the endpoint classification: 
Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=900

​
Header Components

DirectiveMeaning
publicResponse can be stored by any cache (browser, CDN)
privateResponse is user-specific, only browser can cache
max-age=NBrowser cache duration in seconds
s-maxage=NCDN/shared cache duration in seconds
stale-while-revalidate=NServe stale data for N seconds while refreshing in background
no-store, no-cache, must-revalidateNo caching at all (realtime endpoints)

​
Example Headers by Endpoint Type

Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=900
Vary: Accept-Language
ETag: "abc123"

​
ETag Support

The API supports both strong and weak ETags for conditional requests:
ETag TypeFormatUsed For
Strong"abc123"Static, catalog, and detail endpoints where byte-level equality matters
WeakW/"abc123"Search, AI-generated, and user data where semantic equivalence is sufficient

​
Conditional Requests

Clients can send If-None-Match headers to check if their cached version is still valid: 
# First request - get the ETag
curl -i "https://tiwih-api.vercel.app/api/v1/strains/slug/blue-dream"
# ETag: "abc123"

# Subsequent request - use conditional request
curl -i "https://tiwih-api.vercel.app/api/v1/strains/slug/blue-dream" \
  -H 'If-None-Match: "abc123"'
# Returns 304 Not Modified if unchanged (no body, saves bandwidth)

​
Conditional Response Optimization

The caching middleware inspects response content and adjusts headers dynamically:
ConditionCache Behavior
Error responsesCache-Control: no-cache (never cache errors)
Empty array resultsShort cache: max-age=60
Large list results (100+ items)Extended cache: max-age doubled
Response has timestamp/lastModifiedLast-Modified header added
An X-Item-Count header is added to list responses: 
X-Item-Count: 47

​
YouTube Video Cache

YouTube video data uses a specialized 30-day cache in Supabase to optimize YouTube API quota usage (10,000 units/day limit).
AspectValue
Cache Tableyoutube_video_cache in Supabase
TTL30 days
Quota Savings~10x more efficient than pipeline-based fetching
FallbackReturns YouTube search URL when quota is exhausted
# Fetches from cache or YouTube API
curl "https://tiwih-api.vercel.app/api/v1/strains/slug/blue-dream/youtube"

# Check cache statistics
curl "https://tiwih-api.vercel.app/api/v1/strains/youtube/cache-stats"

​
Cache Invalidation

Write operations (POST, PUT, PATCH, DELETE) automatically trigger cache invalidation for related content:
Path PatternInvalidated Tags
/strains/*strains, catalog, search
/users/*, /orders/*, /sessions/*user_data
Invalidation tags are sent via the X-Cache-Invalidate response header for CDN integration: 
X-Cache-Invalidate: strains,catalog,search

​
Cache Warming

The API includes proactive cache warming that triggers on approximately 0.1% of requests. It pre-populates cache entries for popular endpoints to reduce cold-cache latency for common queries.

​
Cache Analytics

Cache performance is tracked internally with hit/miss/bypass counts per endpoint type. In development, analytics are periodically logged: 
[CacheAnalytics] Performance: {
  hitRate: 0.73,
  missRate: 0.22,
  bypassRate: 0.05,
  totalRequests: 14520
}
The X-Cache-Status header indicates the cache outcome:
ValueMeaning
HITResponse served from cache
MISSCache miss, response generated fresh
(absent)Cache bypassed (non-GET, realtime endpoint)

​
Debug Headers (Development Only)

In development mode, additional debugging headers are included: 
X-Endpoint-Type: catalog
X-Cache-Strategy: enabled
X-Cache-TTL: 300
X-Cache-MaxAge: 300
These headers are not sent in production.