Nextjs Endpoint Rules

Keep endpoints boring, typed, and thin.

Choose the Right Surface

• Use a server action for same-app form mutations and button-triggered commands.
• Use a route handler for external consumers, webhooks, uploads, downloads, streaming, or public/private HTTP APIs.
• Do not create a route handler only to proxy an internal component call unless an HTTP boundary is genuinely needed.

Handler Workflow

1. Parse params, search params, headers, and body.
2. Validate input at the boundary.
3. Authenticate and authorize.
4. Delegate to a use-case or service.
5. Map the result to a stable HTTP contract.
6. Add cache or idempotency behavior if needed.
7. Return structured success/error payloads.

Contract Rules

• Success shape: { data, meta? }
• Error shape: { error: { code, message, details? }, meta?: { requestId? } }