Stateless Counter APIs: Architecting Zero-Friction Telemetry for Static Frontends

Current Situation Analysis

Modern web telemetry has drifted heavily toward complexity. Teams routinely deploy full analytics suites, event tracking SDKs, and cloud data warehouses just to answer a single question: how many times has this resource been accessed? The architectural overhead required to maintain these systems often dwarfs the actual value delivered for simple counting use cases. Page views, download clicks, button interactions, and README badges all share a common requirement: a monotonically increasing integer with minimal latency.

This gap became glaringly apparent when countapi.xyz disappeared without warning or migration paths. The service thrived precisely because it eliminated every standard friction point in API design: no authentication headers, no account creation, no SDK dependencies, and no namespace hierarchies. It was a pure HTTP GET interface that returned a JSON payload containing an updated counter. When it vanished, developers were forced to choose between over-provisioning a relational database, integrating heavyweight analytics platforms, or abandoning simple telemetry altogether.

The community response materialized as countapi.mileshilliard.com, a direct architectural successor built on a Python serverless runtime backed by Redis and deployed on Oracle Cloud Infrastructure. Public monitoring dashboards indicate near 99% uptime, validating the reliability of the underlying stack. The system operates on a flat key-value model where every counter is identified by a single string. This design choice intentionally sacrifices strict isolation in favor of zero-latency request routing and minimal cognitive overhead.

The problem is frequently overlooked because engineering teams conflate "telemetry" with "business intelligence." Simple counters do not require user segmentation, funnel analysis, or GDPR-compliant data pipelines. They require atomic increments, fast reads, and predictable failure modes. By treating lightweight counting as an afterthought, teams accumulate unnecessary infrastructure debt, increase bundle sizes with tracking SDKs, and introduce single points of failure in their frontend rendering pipelines.

WOW Moment: Key Findings

The architectural trade-off between full analytics stacks and stateless counting APIs becomes quantifiable when measuring implementation overhead, runtime performance, and maintenance burden. The following comparison isolates the three most common approaches to frontend telemetry:

Approach	Setup Time	Auth Overhead	Latency (P95)	Infrastructure Cost	Query Flexibility
Full Analytics Stack (GA/Mixpanel)	2–4 hours	High (SDK + Consent)	120–300ms	$0–$500+/mo	High (funnels, cohorts)
Stateless Counting API	5–10 minutes	None	40–80ms	$0 (community)	None (single integer)
Self-Hosted Redis/Postgres	1–2 days	Medium (API Gateway)	15–30ms	$15–$50/mo	Medium (custom endpoints)

This data reveals a critical insight: for pure increment/read workflows, stateless APIs reduce implementation time by over 90% while maintaining sub-100ms response times. The absence of authentication handshakes eliminates TLS negotiation overhead and token validation latency. More importantly, the flat key model removes the need for backend routing logic, allowing edge networks to cache responses aggressively.

Why this matters: Static site generators, documentation portals, and lightweight marketing pages can now host accurate telemetry without provisioning databases, managing API keys, or bloating client bundles. The trade-off is explicit: you sacrifice data granularity and privacy controls in exchange for operational simplicity and immediate deployability. When the requirement is strictly "a number that goes up," this architecture delivers the highest signal-to-noise ratio.

Core Solution

Implementing a stateless counting workflow requires shifting from traditional database patterns to HTTP-first telemetry. The following implementation demonstrates a production-ready TypeScript service that wraps the counting API, handles network resilience, and enforces key naming conventions.

Step 1: Define Key Strategy

Since the API uses a flat namespace, key collision is the primary risk. Adopt a deterministic naming convention that prefixes counters with your domain, project slug, and resource identifier. Example: acme-docs-api-reference-v2. This guarantees uniqueness without requiring server-side validation.

Step 2: Implement the Counter Service

Raw fetch calls lack retry logic, error boundaries, and response caching. A dedicated service class abstracts these concerns while maintaining the zero-auth contract.

interface CounterResponse {
  key: string;
  message: string;
  value: string;
  old_value?: string;
}

interface CounterConfig {
  baseUrl: string;
  timeoutMs?: number;
  maxRetries?: number;
}

export class TelemetryCounter {
  private readonly baseUrl: string;
  private readonly timeout: number;
  private readonly retries: number;

  constructor(config: CounterConfig) {
    this.baseUrl = config.baseUrl.replace(/\/$/, '');
    this.timeout = config.timeoutMs ?? 3000;
    this.retries = config.maxRetries ?? 2;
  }

  private async request<T>(endpoint: string, options?: RequestInit): Promise<T> {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.timeout);

    try {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        ...options,
        signal: controller.signal,
        headers: { Accept: 'application/json' }
      });

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

      return response.json() as Promise<T>;
    } finally {
      clearTimeout(timeoutId);
    }
  }

  private async withRetry<T>(fn: () => Promise<T>): Promise<T> {
    let lastError: Error | undefined;
    for (let attempt = 0; attempt <= this.retries; attempt++) {
      try {
        return await fn();
      } catch (err) {
        lastError = err as Error;
        if (attempt < this.retries) {
          await new Promise(res => setTimeout(res, Math.pow(2, attempt) * 500));
        }
      }
    }
    throw lastError ?? new Error('Counter request failed after retries');
  }

  public async increment(key: string): Promise<string> {
    const data = await this.withRetry(() =>
      this.request<CounterResponse>(`/api/v1/hit/${encodeURIComponent(key)}`)
    );
    return data.value;
  }

  public async read(key: string): Promise<string> {
    const data = await this.withRetry(() =>
      this.request<CounterResponse>(`/api/v1/get/${encodeURIComponent(key)}`)
    );
    return data.value;
  }

  public async set(key: string, targetValue: number): Promise<string> {
    const data = await this.withRetry(() =>
      this.request<CounterResponse>(
        `/api/v1/set/${encodeURIComponent(key)}?value=${targetValue}`
      )
    );
    return data.value;
  }
}

Step 3: Frontend Integration

Wrap the service in a framework-agnostic hook or component. The following example demonstrates a React implementation that gracefully degrades when the network is unavailable.

import { useState, useEffect } from 'react';
import { TelemetryCounter } from './TelemetryCounter';

const counter = new TelemetryCounter({
  baseUrl: 'https://countapi.mileshilliard.com',
  timeoutMs: 2000,
  maxRetries: 1
});

export function usePageCounter(key: string) {
  const [count, setCount] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    let cancelled = false;

    counter.increment(key)
      .then(val => {
        if (!cancelled) setCount(parseInt(val, 10));
      })
      .catch(err => {
        if (!cancelled) setError(err.message);
      });

    return () => { cancelled = true; };
  }, [key]);

  return { count, error };
}

Architecture Decisions & Rationale

• Redis Backend: Redis handles atomic INCR operations in O(1) time. Unlike relational databases, it avoids row-level locking and transaction overhead, making it ideal for high-frequency, low-complexity counters.
• Serverless Python Runtime: Cold starts are acceptable because counter requests are infrequent relative to page loads. The runtime scales to zero during idle periods, minimizing idle compute costs.
• Public Keys by Design: Removing authentication eliminates token validation, CORS preflight complexity, and key rotation overhead. The trade-off is that any client can read or increment a counter, which is acceptable for public telemetry but unsuitable for private metrics.
• Flat Namespace: Collapsing namespace/key hierarchies reduces URL parsing complexity and enables straightforward CDN caching rules. Key uniqueness becomes a client-side responsibility, enforced through naming conventions.

Pitfall Guide

1. Key Collision Through Poor Naming

Explanation: The API uses a global key space. Using generic names like visits or clicks guarantees collisions with other users' counters. Fix: Implement a strict naming convention: {domain}-{project}-{resource}-{version}. Hash long identifiers if necessary, but keep them human-readable for debugging.

2. Ignoring Rate Limit Boundaries

Explanation: The service enforces generous but real rate limits. Bursting requests during traffic spikes or running aggressive polling loops will trigger temporary blocks. Fix: Cache responses client-side for at least 60 seconds. Implement exponential backoff on 429 responses. Never poll the /get endpoint faster than once per minute.

3. Treating Counters as Secure Data

Explanation: All keys are publicly readable. Anyone who guesses or discovers your key can read its current value or increment it. Fix: Never use this API for sensitive metrics, internal KPIs, or gated content tracking. Reserve it strictly for public-facing telemetry where data exposure carries zero risk.

4. Synchronous UI Blocking

Explanation: Awaiting counter responses before rendering content delays Time to Interactive. Network failures will break the user experience if not handled. Fix: Use fire-and-forget patterns for increments. Display a placeholder or cached value immediately, then update asynchronously. Always provide a fallback UI state for network errors.

5. Client-Side Hit Skew

Explanation: Browser extensions, ad blockers, and bot traffic frequently strip or block tracking requests. Relying solely on client-side hits underreports actual traffic by 15–30%. Fix: For accurate metrics, proxy counter increments through your own backend. Your server can make authenticated requests to the counting API, bypassing client-side blockers and providing a single source of truth.

6. Missing Noscript Fallback

Explanation: Static documentation sites, README renderers, and email newsletters often disable JavaScript. Client-side fetch calls will never execute in these environments. Fix: Use a hidden tracking pixel that triggers the /hit endpoint on image load. Example: <img src="https://countapi.mileshilliard.com/api/v1/hit/your-key" alt="" style="display:none;" />. This works across all HTML-capable renderers.

7. Overlooking Health Endpoints

Explanation: Assuming the service is always available leads to silent failures. Network partitions or upstream outages will cause counter requests to hang or fail. Fix: Implement circuit breakers that monitor /api/v1/status and /health. If the service returns degraded status, switch to local storage counters or disable telemetry temporarily to preserve UX.

Production Bundle

Action Checklist

• Define a deterministic key naming convention and document it in your team's style guide
• Implement response caching with a minimum 60-second TTL to respect rate limits
• Add exponential backoff and retry logic for network failures and 429 responses
• Use fire-and-forget patterns for increments to avoid blocking UI rendering
• Deploy a noscript tracking pixel fallback for static or no-JS environments
• Monitor /api/v1/status and implement circuit breakers for service degradation
• Evaluate self-hosting via the open-source repository if data residency or uptime SLAs become critical

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Personal blog, README badges, static docs	Stateless Counting API	Zero setup, no auth, instant deployment	$0
Marketing site with conversion tracking	Full Analytics Stack	Requires funnel analysis, user segmentation, consent management	$0–$500+/mo
Internal dashboard, gated content metrics	Self-Hosted Redis/Postgres	Requires data isolation, audit trails, and strict access control	$15–$50/mo
High-traffic SaaS product	Hybrid (Proxy + Analytics)	Client-side blocks skew data; server-side proxy ensures accuracy	$50–$200/mo

Configuration Template

Copy this TypeScript configuration to standardize counter usage across your codebase. It includes environment-aware base URLs, timeout tuning, and centralized error handling.

// config/telemetry.ts
export const TELEMETRY_CONFIG = {
  baseUrl: process.env.NODE_ENV === 'production'
    ? 'https://countapi.mileshilliard.com'
    : 'https://countapi.mileshilliard.com', // Fallback to production for dev simplicity
  timeoutMs: 2500,
  maxRetries: 2,
  cacheTTL: 60_000, // 60 seconds
  keyPrefix: process.env.APP_NAME ?? 'default-app',
  enabled: process.env.DISABLE_TELEMETRY !== 'true'
} as const;

// utils/counter-key.ts
export function buildCounterKey(resource: string, version?: string): string {
  const base = `${TELEMETRY_CONFIG.keyPrefix}-${resource}`.toLowerCase().replace(/\s+/g, '-');
  return version ? `${base}-v${version}` : base;
}

Quick Start Guide

1. Install dependencies: No packages required. The API uses standard fetch, available in all modern browsers and Node.js 18+.
2. Initialize the service: Import the TelemetryCounter class and instantiate it with your base URL and timeout preferences.
3. Define your key: Use the buildCounterKey utility to generate a collision-resistant identifier following the {prefix}-{resource} pattern.
4. Trigger an increment: Call counter.increment(key) on page load or button click. Handle the response asynchronously and update your UI.
5. Verify operation: Open browser dev tools, check the Network tab for successful 200 responses, and confirm the returned value increments as expected.

Stateless counting APIs strip away the ceremony of modern telemetry while preserving the core requirement: a reliable, low-latency integer that reflects resource engagement. By enforcing strict key conventions, implementing resilient network patterns, and acknowledging the public nature of the data, teams can deploy accurate telemetry in minutes rather than days. The architecture trades granular analytics for operational velocity, making it the optimal choice for static frontends, documentation portals, and lightweight tracking workflows where simplicity is the primary metric.