controller-api-implementation

To keep API controllers thin, implement them as transport adapters that only parse, validate, and map requests to contract-compliant responses while delegating all business decisions to the application layer. This isolates business logic from the transport layer.

Format API error responses using RFC 7807 Problem Details by transforming service errors at the safe boundary without leaking internal messages or stack traces. This ensures correct HTTP status-code mapping and consistent contract-aligned error handling.

Handle request validation and auth context extraction in HTTP handlers by applying trusted-boundary validation immediately upon deserialization. Extract the auth context at the boundary before delegating execution to the application layer.

Yes, the transport adapter pattern works for both HTTP handlers and gRPC server methods. It handles route dispatch, request deserialization, content negotiation, and idempotency key handling across different protocol implementations.

API responses leak internal stack traces because error boundaries are not properly isolated. Transform errors into RFC 7807 Problem Details at the controller boundary to map status codes correctly without exposing internal messages or topology details.

Implement idempotency key format validation and correlation-aware logging by enforcing security guardrails at the trusted boundary. Capture correlation context during request parsing to maintain strict forbidden responsibilities for maintainability.