Our API is built with Hono on Cloudflare Workers, optimizing for low latency and global distribution. Here's how we build and maintain it.
Hono Framework
We chose Hono for its lightweight footprint and edge-first design:
- Tiny bundle: Hono adds minimal overhead to Worker size, keeping cold starts fast.
- Familiar patterns: Express-like routing makes onboarding easy for developers.
- Built-in middleware: CORS, compression, and logging work out of the box.
- Type safety: Full TypeScript support with request/response typing.
Edge-First Design
Every API decision considers edge deployment constraints:
- Stateless handlers: No server-side sessions or local storage between requests.
- External state: All state lives in Supabase (SQL), Cloudflare KV (key-value), or R2 (blobs).
- Cold start optimization: Lazy initialization of heavy clients (Stripe, Supabase) only when needed.
- Regional routing: Cloudflare automatically routes requests to the nearest edge location.
Request Validation
Zod provides runtime type safety for all incoming data:
- Schema definitions: Every endpoint defines its expected input shape with Zod schemas.
- Automatic parsing: Invalid requests fail fast with clear error messages.
- Type inference: TypeScript types are derived from schemas, ensuring consistency.
- Transformations: Zod handles coercion (string to number) and defaults cleanly.
Error Handling
Consistent error responses make debugging easier:
- Structured format: All errors return JSON with
error,message, and optionaldetails. - HTTP status codes: We use appropriate codes (400 for validation, 401 for auth, 403 for permissions, 429 for rate limits).
- Error tracking: Exceptions are logged with request context for debugging.
- User-friendly messages: Technical details are logged but not exposed to clients.
Rate Limiting
Our rate limiting strategy protects the system while being fair:
- Tiered limits: Different limits for tracking endpoints (high), API endpoints (medium), and auth endpoints (low).
- Per-key tracking: API keys have individual quotas based on subscription tier.
- Sliding window: Limits are calculated over rolling time windows, not fixed periods.
- Graceful degradation: Rate-limited requests receive
Retry-Afterheaders.
Endpoint Organization
Routes are organized by domain for maintainability:
/e/:trackingCode— Public tracking (ad-blocker friendly)/api/analytics/*— Dashboard data queries/api/replay/*— Session replay management/api/billing/*— Stripe integration/api/team/:teamId/*— Team-scoped operations/api/external/v1/*— Third-party API access/api/cron/*— Scheduled task triggers (webhook auth)