public-api-design

# Public API Design ## Fail-Fast Rule If authentication fails, **return immediately** with a structured error. Never leak internal error details, stack traces, or database schemas in public API responses. Never serve stale or partial data without explicit quality flags. API consumers make automated trading decisions — wrong data is worse than no data. ## Cardinal Rule **The public API is a product, not an endpoint.** It needs versioning, documentation, rate limits, error contracts, deprecation policy, and developer experience design — not just working routes. An undocumented API with no error contract is a support ticket generator. ## Architecture: Admin Keys vs User Keys {{PROJECT_NAME}} currently has `api-keys.ts` with admin-only key management. The public API requires a second layer: **user self-service keys**. ``` ┌─────────────────────────────────┐ │ API Key Types │ ├─────────────────────────────────┤ │ │ │ Admin Keys (existing) │ │ ├── Managed via /admin panel │ │ ├── Full access (read/write) │ │ ├── Created by the Owner only │ │ └── Stored in AdminConfig │ │ │ │ User Keys (new) │ │ ├── Self-service via /settings │ │ ├── Scoped by user's tier │ │ ├── Rate limited per tier │ │ ├── Stored in Supabase │ │ └── Tied to user_id via RLS │ │ │ └─────────────────────────────────┘ ...