jhonatan-oliveiradev Building Reliable Node API Boundaries
Core principle
Treat every API boundary as a trust boundary. Make authentication, authorization, validation, mutation scope, and failure behavior explicit before optimizing handler structure or framework ergonomics.
Request path
- Parse the request into a bounded shape. Reject malformed or oversized input before business work begins.
- Authenticate the caller, then authorize the requested object and properties. Never infer object-level authorization only from a valid session.
- Validate domain input separately from transport parsing. Reject fields the caller is not allowed to set instead of mass-assigning request bodies.
- Keep one clear business operation per boundary. Put atomic database mutations inside an intentional transaction boundary.
- For externally retryable writes, define idempotency or conflict semantics before shipping the endpoint.
- Map internal failures to stable public error responses without leaking implementation details.
- Add request correlation and structured diagnostics. Use framework context when adequate; otherwise Node.js
AsyncLocalStoragecan carry request-scoped context across asynchronous work. - Put timeouts, cancellation, pagination, and resource ceilings around downstream or potentially expensive work.
Authorization checks
Cover both:
- object-level access: may this caller act on this specific record?
- property/function-level access: may this caller read or mutate these fields or operations?
Do not rely on a client to hide forbidden identifiers or fields.
Verification
Exercise at minimum:
- a valid request;
- malformed and oversized input;
- valid identity with unauthorized object access;
- partial/property-level permission failure;
- repeated write or replay behavior where relevant;
- downstream timeout/failure;
- transaction rollback after a mid-operation error.
Logs should carry correlation and outcome context without storing secrets or unnecessary personal data.
References
- Node.js AsyncLocalStorage: https://nodejs.org/api/async_context.html
- OWASP API Security Top 10 2023: https://owasp.org/API-Security/editions/2023/en/0x11-t10/