API Conventions rules

Validate inputs and preconditions up-front and return early before issuing any database queries.

Provide an authenticated endpoint that assembles a user's data into a structured JSON export and returns a short-lived signed URL (≤24h). Include integration tests in the PR. (GDPR Art. 20)

Endpoints under /admin or privileged routes that can view or export ePHI must enforce multi-factor authentication and recent re-auth (e.g., within 15 minutes).

API endpoints should return an explicit status code and minimal error body on failures; avoid 200 with error payload.

Return 2xx only on success; use 4xx for client errors and 5xx for server errors, with a minimal JSON error body.

Handlers must return non-2xx status codes for error outcomes and include a minimal error body that does not leak sensitive details.

Return 2xx on success, 4xx for client errors, and 5xx for server errors with minimal, non-sensitive bodies.

Ensure that HTTP handlers return the appropriate status codes based on request success or failure.

For web/mobile payment forms, send PAN and CVV directly to the PCI-compliant gateway to obtain a single-use token; submit only the token to your backend. Validate that backend APIs reject requests containing PAN/SAD. (PCI DSS scoping & SAQ A)

Ensure that optional REST parameters use object types or `Optional<T>` instead of primitive types to avoid runtime errors.

Without ProducesResponseTypeAttribute, Swagger cannot infer the response type of an action returning IActionResult, making API documentation unclear and unreliable.

Prefer app/api route handlers over legacy pages/api. Return NextResponse.json, validate input, and handle allowed HTTP methods explicitly.

After decoding, assert required keys and types before use; reject unexpected shapes.

Validate and sanitize all request bodies and search params on the server using a schema (e.g., zod). Reject invalid payloads with proper status.

If a PR changes an API endpoint/controller/route, assess current production health before adding heavier logic. - If a monitoring MCP is available (Datadog/Grafana): query current p95 latency and error rate for that endpoint. - If the endpoint is already degraded, warn against adding heavy queries, blocking I/O, or complex synchronous logic; require performance evidence or a safe rollout plan. To enable this check, the PR should reference the endpoint path (e.g., `POST /api/payments`) or the controller/action name.

For any handler that reads or writes ePHI, write an append-only audit record with user id, patient id, action (READ_PHI/WRITE_PHI), purpose-of-use, timestamp, and request id. Prevent deletion or mutation of audit entries.

Configure CookiePolicyOptions to enforce SameSite=Lax or Strict, HttpOnly, and Secure for all auth cookies.

Set HTTP headers for payment entry points and CHD-adjacent responses to prevent storage: Cache-Control: no-store, Pragma: no-cache, and appropriate privacy headers. Ensure intermediaries cannot cache PAN-related flows.

Provide subject data export in JSONL or CSV only after confirming lawful basis (consent/contract). Include schema version and exclude internal linkage keys.

For HTTP/RPC handlers, parse+validate inputs in dedicated functions. Return typed errors and reuse across endpoints.

Replace long parameter lists with request objects or records; validate them as a unit.

When using Optional/CompletableFuture/Publisher-like types, map empty values to a clear outcome (e.g., 404) rather than returning null.

Validate CPF/CNPJ format and checksum server-side; reject storage of invalid identifiers and never auto-correct them. Store normalized (digits-only) representation.

For simple form submissions from RSC, use server actions with schema validation and then revalidate paths/tags. Avoid client fetch for trivial mutations.