API Conventions rules

Handlers must verify the requester’s role and a valid consent/relationship (e.g., care team assignment) before disclosing ePHI; include Purpose-Of-Use in the decision and audit the outcome.

If data subject is a child/adolescent, require age verification and parental/legal guardian consent prior to processing; deny processing otherwise and do not store the payload.

For Ingress/Service of type LoadBalancer, require host/path allowlist and TLS; forbid 0.0.0.0/0 exposure without WAF or Auth.

Public services must require TLSv1.2 or higher and set HSTS (max-age ≥ 15552000, includeSubDomains). Reject plaintext HTTP and weak ciphers; cookies must be Secure and HttpOnly with SameSite set.

Before handling sensitive personal data (e.g., health, biometric), verify a valid consent record and attach its ID to the processing context. Provide a path to revoke consent and stop further processing.

Validate HTTP status and safely access nested response data using `dig`/guards.

Validate presence, format, and ranges for incoming parameters before processing.

Validate presence, type, and range of critical inputs at boundaries (API, CLI, jobs) and fail fast with clear messages.

Check transport errors and HTTP status codes before parsing response bodies; treat 4xx/5xx as errors with context.

Without explicit HTTP method attributes, API behavior can be unclear, leading to route conflicts and unexpected results.

Verify that API controllers inherit from `ControllerBase` instead of `Controller` unless views are explicitly required.

Starting a route template with '/' in ASP.NET makes it absolute, ignoring controller-level routes and potentially breaking expected routing behavior.

Data subject export endpoints must whitelist fields and redact internal notes, tokens, and third-party IDs. Generate machine-readable output and log the lawful basis for the export.

When reading from PHI tables, project only authorized fields and avoid SELECT *. Implement whitelists per role and document them. Reject requests lacking a Purpose-Of-Use justification.

Use helmet to set HSTS and configure cookies with Secure, HttpOnly, and SameSite. Reject HTTP by redirecting to HTTPS.

Force HTTPS via middleware, set HSTS, and configure session cookies with secure=true, http_only=true, same_site=lax or strict in config/session.php.

Applications serving ePHI must require HTTPS, disable insecure ciphers, and enable HSTS with preload and includeSubDomains. Reject cleartext HTTP requests.

Ensure that `@PathVariable` is used correctly in Spring applications to bind URI path variables to method parameters.

Only set analytics/marketing cookies if consent.purposes.analytics === true and consent.version matches current policy; re-check on version bump. (GDPR Art. 7, ePrivacy)

Any code path that reads, decrypts, or exchanges PAN tokens must require an explicit authorization policy (e.g., role "pci:read_token") and log access without PAN. Deny by default. (PCI DSS 4.0 Req. 7 & 10)

Rescue RecordNotFound and return 404 (or domain-appropriate response) instead of 500.

Set session idle timeout ≤ 15 minutes and absolute timeout ≤ 12 hours; cookies must be Secure, HttpOnly, and SameSite=Lax or Strict; revoke sessions on password change.

Collect only strictly necessary fields for the declared purpose; mark optional PII as nullable and omit from payloads when empty. Fail requests that include undeclared extra PII keys.

Configure Spring Boot to require client certificates for internal APIs (clientAuth=REQUIRE) and restrict CAs; log peer certificate subject in audit events.