docs(event-handler): added documentation for support for HTTP API, ALB and FURL (#4795)

Co-authored-by: Stefano Vozza <[email protected]>

Author: sdangol

docs/features/event-handler/rest.md

@@ -7,11 +7,11 @@ status: new
 !!! warning "Feature status"
      This feature is under active development and may undergo significant changes. We recommend using it in non-critical workloads and [providing feedback](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose){target="_blank"} to help us improve it.
 
-Event handler for Amazon API Gateway REST <!-- and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, and VPC Lattice -->.
+Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), and Lambda Function URLs<!--, and VPC Lattice -->.
 
 ## Key Features
 
-* Lightweight routing to reduce boilerplate for API Gateway REST (HTTP API, ALB and Lambda Function URLs coming soon)
+* Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
 * Built-in middleware engine for request/response transformation (validation coming soon).
 * Works with micro function (one or a few routes) and monolithic functions (see [Considerations](#considerations)).
 
@@ -27,24 +27,45 @@ npm install @aws-lambda-powertools/event-handler
 
 ### Required resources
 
-If you're using any API Gateway integration, you must have an existing [API Gateway Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"}<!--  or [ALB](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"} --> configured to invoke your Lambda function.
+The event handler works with different types of events. It can process events from API Gateway REST APIs, HTTP APIs, ALB, Lambda Function URLs, and will soon support VPC Lattice as well.
+
+You must have an existing integration configured to invoke your Lambda function depending on what you are using:
+
+| Integration               | Documentation                                                                                                                                |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| API Gateway REST API      | [Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html){target="_blank"}     |
+| API Gateway HTTP API      | [Proxy integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html){target="_blank"} |
+| Application Load Balancer | [ALB configuration](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/lambda-functions.html){target="_blank"}              |
+| Lambda Function URL       | [Function URL configuration](https://docs.aws.amazon.com/lambda/latest/dg/urls-configuration.html){target="_blank"}                          |
 
 <!-- In case of using [VPC Lattice](https://docs.aws.amazon.com/lambda/latest/dg/services-vpc-lattice.html){target="_blank"}, you must have a service network configured to invoke your Lambda function. -->
 
-This is the sample infrastructure for API Gateway <!-- and Lambda Function URLs --> we are using for the examples in this documentation. There is no additional permissions or dependencies required to use this utility.
+This is the sample infrastructure for the different integrations we are using for the examples in this documentation. There is no additional permissions or dependencies required to use this utility.
 
 ??? "See Infrastructure as Code (IaC) examples"
-    === "API Gateway SAM Template"
+    === "API Gateway REST API SAM Template"
+
+        ```yaml title="AWS Serverless Application Model (SAM) example"
+        --8<-- "examples/snippets/event-handler/rest/templates/api_gateway_rest_api.yml"
+        ```
+    
+    === "API Gateway HTTP API SAM Template"
 
         ```yaml title="AWS Serverless Application Model (SAM) example"
-        --8<-- "examples/snippets/event-handler/rest/templates/api_gateway.yml"
+        --8<-- "examples/snippets/event-handler/rest/templates/api_gateway_http_api.yml"
+        ```
+    
+    === "Lambda Function URL SAM Template"
+
+        ```yaml title="AWS Serverless Application Model (SAM) example"
+        --8<-- "examples/snippets/event-handler/rest/templates/lambda_furl.yml"
         ```
 
 ### Route events
 
-Before you start defining your routes, it's important to understand how the event handler works with different types of events. The event handler can process events from API Gateway REST APIs, and will soon support HTTP APIs, ALB, Lambda Function URLs, and VPC Lattice as well.
+When a request is received, the event handler automatically detects the event type and converts it into a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request){target="_blank"} object.
 
-When a request is received, the event handler will automatically convert the event into a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and give you access to the current request context, including headers, query parameters, and request body, as well as path parameters via typed arguments.
+You get access to headers, query parameters, request body, and path parameters via typed arguments. The response type is determined automatically based on the event.
 
 #### Response auto-serialization
 
@@ -71,6 +92,9 @@ For your convenience, when you return a JavaScript object from your route handle
     --8<-- "examples/snippets/event-handler/rest/samples/gettingStarted_serialization.json"
     ```
 
+!!! tip "Automatic response format transformation"
+    The event handler automatically ensures the correct response format is returned based on the event type received. For example, if your handler returns an API Gateway v1 proxy response but processes an ALB event, we'll automatically transform it into an ALB-compatible response. This allows you to swap integrations with little to no code changes.
+
 ### Dynamic routes
 
 You can use `/todos/:todoId` to configure dynamic URL paths, where `:todoId` will be resolved at runtime.

examples/snippets/event-handler/rest/templates/api_gateway_http_api.yml

@@ -0,0 +1,48 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Hello world event handler API Gateway HTTP API
+
+Globals:
+  HttpApi:
+    CorsConfiguration:
+      AllowOrigins:
+        - https://example.com
+      AllowHeaders:
+        - Content-Type
+        - Authorization
+        - X-Amz-Date
+      MaxAge: 300
+
+  Function:
+    Timeout: 5
+    MemorySize: 256
+    Runtime: nodejs22.x
+    Tracing: Active
+    Environment:
+      Variables:
+        POWERTOOLS_LOG_LEVEL: INFO
+        POWERTOOLS_SERVICE_NAME: hello
+
+Resources:
+  ApiFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      CodeUri: hello_world
+      Description: API handler function
+      Events:
+        AnyApiEvent:
+          Type: HttpApi
+          Properties:
+            Path: /{proxy+}
+            Method: ANY
+        GetAllTodos:
+           Type: HttpApi
+           Properties:
+             Path: /todos
+             Method: GET
+        GetTodoById:
+           Type: HttpApi
+           Properties:
+             Path: /todos/{todo_id}
+             Method: GET

examples/snippets/event-handler/rest/templates/api_gateway.yml renamed to examples/snippets/event-handler/rest/templates/api_gateway_rest_api.yml

@@ -1,6 +1,6 @@
 AWSTemplateFormatVersion: "2010-09-09"
 Transform: AWS::Serverless-2016-10-31
-Description: Hello world event handler API Gateway
+Description: Hello world event handler API Gateway REST API
 
 Globals:
   Api:

examples/snippets/event-handler/rest/templates/lambda_furl.yml

@@ -1,6 +1,6 @@
 AWSTemplateFormatVersion: "2010-09-09"
 Transform: AWS::Serverless-2016-10-31
-Description: Hello world event handler API Gateway
+Description: Hello world event handler Lambda Function URL
 
 Globals:
   Function: