api

API Layer

Constraints

• Location: Place all HTTP calls under features/[feature]/api.
• Validation: Use Zod for input/output validation when data is external or untrusted. Parse responses before they reach UI or state.
• Return Type: Return typed data, not raw responses.
• Contract First: ALWAYS define TypeScript/Zod contracts before writing the implementation. Every public behavior is a commitment.
• Error Handling: Normalize HTTP failures to a consistent ApiError (code, message, details) before throwing.
• Pagination & Limits: Unbounded data fetching is FORBIDDEN. Always enforce pagination or limits on list requests.
• HTTP Client Strategy:
  • CRITICAL CHECK: Check package.json to determine the project's HTTP client.
  • Default (ViraStack): Prefer a centralized native fetch wrapper (e.g., src/lib/api.ts) when axios is not installed.
  • If axios is installed, use a centralized axios instance (e.g., src/lib/api.ts) instead.
  • Match the wrapper's return shape: fetch wrappers typically return T directly; axios returns { data }.
• Interceptors: Handle cross-cutting concerns (auth, headers, JSON parsing, retries) within the centralized client/wrapper.
• Naming: verb-entity.api.ts (e.g., get-users.api.ts). Function: getUsers.
• SSR Safety: Use only whitelisted internal URLs or absolute paths for server-to-server calls to prevent SSRF.

Bans

• Raw Exposure: Forbidden to use raw API data inside UI components, hooks, or state without validation.
• Logic Leaks: Forbidden to leak internal error stack traces or raw errors to the client.
• Security: Forbidden to construct dynamic URLs using unsanitized user inputs.
• Architecture: NEVER make raw HTTP calls (fetch() or axios.get()) directly inside feature components or hooks. Always use the project's centralized API client/wrapper. No cross-feature API imports, no hardcoded endpoint strings in queries.

Mandatory Patterns