docs(event-handler): create main structure

Author: dreamorosi

docs/features/event-handler/bedrock-agents.md

@@ -1,7 +1,6 @@
 ---
 title: Bedrock Agents
 description: Event Handler for Amazon Bedrock Agents
-status: new
 ---
 
 <!-- markdownlint-disable MD043 -->

docs/features/event-handler/index.md

@@ -7,6 +7,14 @@ description: Simplify routing and processing of events in AWS Lambda functions
 
 <div class="grid cards" markdown>
 
+- __REST APIs__
+
+    ---
+
+    Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Balancer (ALB), Lambda Function URLs, and VPC Lattice.
+
+    [:octicons-arrow-right-24: Read more](./rest.md)
+
 - __AppSync Events API__
 
     ---

docs/features/event-handler/api-gateway.md renamed to docs/features/event-handler/rest.md

@@ -1,28 +1,26 @@
 ---
 title: REST API
-description: Core utility
+description: Event handler for building REST APIs in AWS Lambda
+status: new
 ---
 
-<!-- markdownlint-disable MD013 -->
-???+ warning "Don't use in production (yet)"
-    This feature is currently under development. As such it's considered not stable and we might make significant breaking changes before going [before its release](https://github.com/aws-powertools/powertools-lambda-typescript/milestone/17){target="_blank"}. You are welcome to [provide feedback](https://github.com/aws-powertools/powertools-lambda-typescript/issues/413){target="_blank"} and [contribute to the project](../../contributing/getting_started.md){target="_blank"}.
+!!! 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) 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.
 
 ## Key Features
 
 * Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs.
-* Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer
-* Built-in integration with [Parser](../../features/parser.md){target="_blank"} for easy payload validation and parsing
+* Built-in middleware engine for request/response transformation and validation.
 * Works with micro function (one or a few routes) and monolithic functions (all routes)
 
 ## Getting started
 
-???+ tip
-    All examples shared in this documentation are available within the [project repository](https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/examples/snippets/event-handler){target="_blank"}.
-
 ### Install
 
+!!! info "This is not necessary if you're installing Powertools for AWS Lambda (TypeScript) via [Lambda layer](../../getting-started/lambda-layers.md)."
+
 ```shell
 npm install @aws-lambda-powertools/event-handler
 ```
@@ -40,13 +38,13 @@ This is the sample infrastructure for API Gateway and Lambda Function URLs we ar
 === "API Gateway SAM Template"
 
     ```yaml title="AWS Serverless Application Model (SAM) example"
-[//]: # (    --8<-- "examples/snippets/event-handler/rest/templates/template.yaml")
+    --8<-- "examples/snippets/event-handler/rest/templates/api_gateway.yml"
     ```
 
 === "Lambda Function URL SAM Template"
 
     ```yaml title="AWS Serverless Application Model (SAM) example"
-[//]: # (    --8<-- "examples/event_handler_lambda_function_url/sam/template.yaml")
+    --8<-- "examples/snippets/event-handler/rest/templates/lambda_furl.yml"
     ```
 
 <!-- remove line below while editing this doc & put it back until the doc has reached its first draft -->

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

@@ -0,0 +1,68 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Hello world event handler API Gateway
+
+Globals:
+  Api:
+    TracingEnabled: true
+    Cors: # see CORS section
+      AllowOrigin: "'https://example.com'"
+      AllowHeaders: "'Content-Type,Authorization,X-Amz-Date'"
+      MaxAge: "'300'"
+    BinaryMediaTypes: # see Binary responses section
+      - "*~1*" # converts to */* for any binary type
+      # NOTE: use this stricter version if you're also using CORS; */* doesn't work with CORS
+      # see: https://github.com/aws-powertools/powertools-lambda-python/issues/3373#issuecomment-1821144779
+      # - "image~1*" # converts to image/*
+      # - "*~1csv" # converts to */csv, eg text/csv, application/csv
+
+  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: Api
+          Properties:
+            # NOTE: this is a catch-all rule to simplify the documentation.
+            # explicit routes and methods are recommended for prod instead (see below)
+            Path: /{proxy+} # Send requests on any path to the lambda function
+            Method: ANY # Send requests using any http method to the lambda function
+
+
+        # GetAllTodos:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos
+        #     Method: GET
+        # GetTodoById:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos/{todo_id}
+        #     Method: GET
+        # CreateTodo:
+        #   Type: Api
+        #   Properties:
+        #     Path: /todos
+        #     Method: POST
+
+        ## Swagger UI specific routes
+
+        # SwaggerUI:
+        #     Type: Api
+        #     Properties:
+        #         Path: /swagger
+        #         Method: GET

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

@@ -0,0 +1,30 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: Hello world event handler API Gateway
+
+Globals:
+  Function:
+    Timeout: 5
+    MemorySize: 256
+    Runtime: nodejs22.x
+    Tracing: Active
+    Environment:
+      Variables:
+        POWERTOOLS_LOG_LEVEL: INFO
+        POWERTOOLS_SERVICE_NAME: hello
+    FunctionUrlConfig:
+      Cors: # see CORS section
+        # Notice that values here are Lists of Strings, vs comma-separated values on API Gateway
+        AllowOrigins: ["https://example.com"]
+        AllowHeaders: ["Content-Type", "Authorization", "X-Amz-Date"]
+        MaxAge: 300
+
+Resources:
+  ApiFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: index.handler
+      CodeUri: hello_world
+      Description: API handler function
+      FunctionUrlConfig:
+        AuthType: NONE # AWS_IAM for added security beyond sample documentation

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
           - features/metrics.md
           - Event Handler:
             - features/event-handler/index.md
+            - features/event-handler/rest.md
             - features/event-handler/appsync-events.md
             - features/event-handler/appsync-graphql.md
             - features/event-handler/bedrock-agents.md
@@ -162,12 +163,6 @@ plugins:
         - snippets/node_modules/*
         - snippets/package.json
         - snippets/CHANGELOG.md
-  - typedoc:
-      source: '.'
-      output_dir: 'api'
-      tsconfig: 'tsconfig.json'
-      options: 'typedoc.json'
-      name: 'API Reference'
 
   - llmstxt:
       markdown_description: Powertools for AWS Lambda (TypeScript) is a developer toolkit to implement Serverless best practices and increase developer velocity. It provides a suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.
@@ -183,6 +178,7 @@ plugins:
           - features/tracer.md
           - features/logger.md
           - features/metrics.md
+          - features/event-handler/rest.md
           - features/event-handler/appsync-events.md
           - features/event-handler/appsync-graphql.md
           - features/event-handler/bedrock-agents.md