docs(event-handler): add documentation for RESt API

[svozza]

Summary

Adds documentation for the event handler REST API

Changes

Getting Started

Added a Getting Started section with the following sections:

• Installation and setup (complete)
• Required AWS resources (complete)
• Route events and request handling (complete)
• Response auto-serialization (complete)
• Dynamic routes with parameters (complete)
• HTTP method handling (complete)
• Data validation (placeholder)
• Handling not found routes (placeholder)
• Error handling (placeholder)
• Throwing HTTP errors (TODO)
• Enabling SwaggerUI (placeholder)
• Custom domains (placeholder)

Getting Started Examples

• gettingStarted_serialization.ts - Response auto-serialization
• gettingStarted_dynamic_routes.ts - Dynamic URL parameters (:todoId)
• gettingStarted_methods.ts - HTTP method handling (GET, POST, etc.)
• gettingStarted_multi_methods.ts - Multiple HTTP methods support

Advanced

Added an Advanced section with the following sections:

• CORS configuration (placeholder)
• Middleware system (complete)
• Fine-grained response control (complete)
• Response streaming (placeholder)
• Compress (placeholder)
• Binary responses (placeholder)
• Debug mode (placeholder)
• OpenAPI integration (placeholder)
• Split routers (placeholder)
• Considerations - Monolithic vs Micro function patterns (complete)

Middleware Section

The Middleware section contains:

• Global middleware using app.use() for application-wide functionality (complete)
• Route-specific middleware for targeted route handling (complete)
• Order of execution with onion pattern execution and pre/post-processing (complete)
• Returning early mechanism for authentication and validation (complete)
• Exception handling patterns (complete)
• Composing middleware (complete)
• Custom middleware (complete)
• Being a good citizen (complete)

Advanced Examples

• advanced_mw_global_middleware.ts - Global middleware with logging
• advanced_mw_route_middleware.ts - Route-specific middleware with timestamps
• advanced_mw_middleware_order.ts - Middleware execution order demonstration
• advanced_mw_early_return.ts - Authentication middleware with early returns
• advanced_fine_grained_responses.ts - Web API Response object for custom headers/status

Considerations Section

Added guidance for Monolithic vs Micro function patterns:

• Trade-offs and considerations
• Deployment strategies
• Performance implications

Visual Documentation

Added visual documentation:

• Mermaid sequence diagrams showing middleware execution flow
• Order of execution visualization for global vs route middleware
• Early return flow diagram for authentication scenarios

Sample JSON Responses

All examples include corresponding Lambda proxy response samples:

• samples/gettingStarted_*.json - Basic feature responses
• samples/advanced_mw_*.json - Middleware execution responses
• samples/advanced_*.json - Advanced feature responses

Infrastructure Templates

Added SAM templates:

• templates/api_gateway.yml - API Gateway proxy integration
• templates/lambda_furl.yml - Lambda Function URL configuration

Issue number: closes #4395

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud