Caching

Implement caching strategies to optimize API performance, reduce latency, and minimize unnecessary requests. Different data types require different time-to-live (TTL) values based on update frequency.

Benefits of Caching

• Performance: Reduced response times and improved user experience for dealers and consumers
• Reliability: Decreased load during peak traffic periods, reducing timeout risks
• Rate limiting: HLC enforces rate limits and may throttle clients with excessive uncached requests
• Cost efficiency: Reduced bandwidth consumption and infrastructure costs

Implementation Strategy

Large-volume dealers typically cache catalog data with 24-hour TTLs while refreshing inventory and pricing data every few minutes to maintain accuracy.

What to cache (and for how long)

Implementation Example

Generic Cache Wrapper

const apiUrl = 'https://api.hlc.bike/us/v3.0'
const apiKey = process.env.HLC_API_KEY

/**
 * Generic cache wrapper supporting Redis, KV stores, or in-memory caching
 * @param {string} key - Cache key
 * @param {number} ttlSeconds - Time to live in seconds
 * @param {Function} fetcher - Async function to fetch fresh data
 */
async function cached(key, ttlSeconds, fetcher) {
  const hit = await cache.get(key)
  if (hit) {
    return JSON.parse(hit)
  }

  const fresh = await fetcher()
  await cache.set(key, JSON.stringify(fresh), ttlSeconds)
  return fresh
}

// Cache brands for 24 hours (86400 seconds)
const brands = await cached('brands', 86400, async () => {
  const response = await fetch(`${apiUrl}/Catalog/Brands`, {
    headers: {
      ApiKey: apiKey,
      language: 'en',
    },
  })

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
  }

  return response.json()
})

// Cache inventory for 5 minutes (300 seconds)
const inventory = await cached(`inventory:${sku}`, 300, async () => {
  const response = await fetch(
    `${apiUrl}/Catalog/Products/Inventory?sku=${sku}`,
    {
      headers: {
        ApiKey: apiKey,
        language: 'en',
      },
    },
  )
  return response.json()
})