Api Design

api-design

The server boundary between UI and database. Validate everything; never trust the caller.

Choose the right tool

• Server Action — form submits / mutations from your own UI. Co-located, type-safe, no manual fetch.
• Route Handler (app/api/.../route.ts) — webhooks, third-party callers, public/REST endpoints, file streams.

Every endpoint

1. Validate input with Zod at the top. Reject early with 400 + a useful message. Re-validate even if the

client already did.

1. Authenticate + authorize: get the user (server), check they may do this. RLS is the backstop, not the

only gate for sensitive actions.

1. Correct status codes: 200/201 success, 400 bad input, 401 unauthenticated, 403 forbidden, 404 missing,

409 conflict, 429 rate-limited, 500 only for true server faults.

1. Handle errors explicitly. Catch, log server-side, return a safe message — never leak stack traces or DB

errors to the client.

1. Rate-limit public/mutating endpoints (e.g. Upstash). Idempotency keys for anything chargeable.
2. Shape responses consistently ({ data } / { error }); don't return raw DB rows with internal columns.

Output

• The handler/action, the Zod schema, the auth check, and the status codes it returns.
• Note what's validated, what's rate-limited, and what an attacker could try.

Guardrails

• No unvalidated input reaching the DB or filesystem.
• No secrets or internal error details in responses.
• Mutations are POST/PUT/PATCH/DELETE, not GET.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: m-binimran
• Source: m-binimran/dev-pack
• License: MIT

Install and usage instructions live in the source repository linked above.