RFC: Event Handler for REST APIs

[dreamorosi]

Is this related to an existing feature request or issue?

#413

Which area does this RFC relate to?

Event Handler

Summary

Resolvers handle request resolution, including one or more routers, and give access to the current event via typed properties.

While the code samples in the RFC will use mainly APIGatewayRestResolver, the first iteration of the feature will have in scope also the APIGatewayHttpResolver and LambdaFunctionUrlResolver resolvers. Other resolvers present in the Python version of Powertools for AWS will be added in subsequent releases and based on demand.

In terms of patterns of usage, Powertools for AWS Lambda (TypeScript) generally supports three patterns:

1. manual usage - most verbose, but usually adoptable in any codebase with minimal changes
2. class method decorator usage - least verbose, but requires adopting an experimental TypeScript feature, and usage of OOP patterns for
3. Middy.js middleware usage - moderately verbose but requires extra 3rd party dependency (@middy/core)

The first iteration of the feature will include only 1/ and 2/, while Middy.js middleware usage will be added later if there's demand.

Use case

Powertools for AWS customers have been asking us to provide a utility similar to the one present in Powertools for AWS Lambda (Python) that allows them to easily build REST APIs backed by an AWS Lambda function.

While there are already many popular frameworks in the Node.js ecosystem such as Express.js, Fastify, and Hono, none of them targets specifically and uniquely Lambda customers, and many enterprise customers who have already adopted Powertools for AWS in their workloads, would prefer a solution delivered by us rather than relying on a 3rd party dependency.

For this reason we are continuing our work to improve feature parity between Powertools for AWS versions and will offer an Event Handler utility in this version. We don't necessarily expect customers who have had success and are happy with other frameworks to migrate to Event Handler; this utility is rather for those who appreciate our commitment to supply chain security and our efforts to build lightweight utilities specifically focused on Lambda.

The goal of this RFC is to propose a feature set that matches the one present in Powertools for AWS Lambda (Python) while also being idiomatic with the Node.js ecosystem and adding selected features that make sense in this version.

Proposal

Response auto-serialization

For your convenience, you can return a plain object response and we will automatically:

• Auto-serialize object (Record<k, v>) responses to JSON
• Include the response under each resolver’s equivalent of a body
• Set Content-Type to application/json
• Set statusCode to 200 (OK)

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/ping', () => {
  return {
    message: 'pong'
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

/* response
{
    "statusCode": 200,
    "multiValueHeaders": {
        "Content-Type": [
            "application/json"
        ]
    },
    "body": "{'message':'pong'}",
    "isBase64Encoded": false
}
*/

If you want full control of the response, headers, and status code you can also return a Response object (more on this later).

Dynamic routes

You can use /todos/:todoId to configure dynamic URL paths, where :todoId will be resolved at runtime.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

class Lambda {
  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

Dynamic paths can also be nested and used at different levels, i.e. /todos/:todoId?/comments/:commentId/hidden/:isHidden and in all cases, the parameters should be strongly typed and customers should get type hints in their IDE like this:

Query Strings

Within app.currentEvent property, you can access all available query strings as an object via query.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/search', () => {
  const query = app.currentEvent.query('q'); // access one at the time

  const { limit, offset } = app.currentEvent.query(); // access multiple at once

  return {
    message: 'Hello, World!'
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Payload

You can access the raw payload via the body property, or if it's a JSON string you can quickly deserialize it via the json() method.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.post('/todo', async () => {
  const rawBody = app.currentEvent.body;

  const body = await app.currentEvent.json();

  return {
    message: 'Hello, World!'
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Headers

Similarly to query strings, you can access headers as dictionary via app.currentEvent.headers. Specifically for headers, it's a case-insensitive dictionary, so all lookups are case-insensitive.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.post('/todo', async () => {
  const apiKey = app.currentEvent.headers.get('X-Api-Key');

  return {
    message: 'Hello, World!'
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Catch-all routes

You can also create things like catch-all routes, for example the .+ expression allows you to handle an arbitrary number of paths within a request.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('.+', () => {
  return {
    message: 'Hello, World!'
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

HTTP Methods

You can use named methods to specify the HTTP method that should be handled in your functions. That is, app.<http_method>, where the HTTP method could be get(), post(), put(), patch(), delete(), head().

If you need to accept multiple HTTP methods in a single function, or support a custom HTTP method for which no method exists (e.g. TRACE), you can use the route() method and pass an array of HTTP methods.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.route('/todos/', () => {
  const data = JSON.parse(app.currentEvent.body || '{}');
  const todos = await fetch(`https://jsonplaceholder.typicode.com/todos`, {
    body: JSON.stringify(data),
  });
  
  return {
    todo: await todos.json(),
  };
}, {
  method: ['PUT', 'POST']
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Below you'll find sections about how we handle routes not found and method not allowed, as well as how to customize the default behavior.

Data validation

All resolvers can optionally coerce and validate incoming requests by setting enableValidation: true.

With this feature, we can now express how we expect our incoming data and response to look like. This moves data validation responsibilities to Event Handler resolvers, reducing a ton of boilerplate code.

You can pass an output schema to signal our resolver what shape you expect your data to be.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { z } from 'zod';

const app = new APIGatewayResolver({
  enableValidation: true,
});

const todoSchema = z.object({
  userId: z.number(),
  title: z.string(),
  completed: z.boolean()
});

app.get('/todo/:todoId', async ({ todoId }) => {
  const response = await fetch(https://jsonplaceholder.typicode.com/todos/${todoId}`);
  const todo = await response.json();

  return todo;
}, {
  validation: {
    output: todoSchema
  }
});

Handling validation errors

Any incoming request that fails validation will lead to a HTTP 422: Unprocessable Entity error response that will look similar to this:

{
  "statusCode": 422,
  "body": "[{\"type\": \"int_parsing\", \"loc\": [\"path\", \"todo_id\"]}]}",
  "isBase64Encoded": false,
  "headers": {
    "Content-Type": "application/json"
  },
  "cookies": []
}

You can customize the error message by catching the RequestValidationError exception. This is useful when you might have a security policy to return opaque validation errors, or have a company standard for API validation errors.

Here's an example where we catch validation errors, log all details for further investigation, and return the same HTTP 422 with an opaque error.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { Logger } from '@aws-lambda-powertools/logger';
import { z } from 'zod';

const app = new APIGatewayResolver({
  enableValidation: true,
});
const logger = new Logger();

app.errorHandler(RequestValidationError, (error) => {
  logger.error('Request validation failed', {
    path: app.currentEvent.path,
    error,
  })
});

const todoSchema = z.object({
  userId: z.number(),
  title: z.string(),
  completed: z.boolean()
});

app.get('/todo/:todoId', async ({ todoId }) => {
  const response = await fetch(https://jsonplaceholder.typicode.com/todos/${todoId}`);
  const todo = await response.json();

  return todo;
}, {
  validation: {
    output: todoSchema
  }
});

Validating payloads

You can do something similar with the incoming payload as well, in this case you can pass a schema to the validation.input property.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { z } from 'zod';

const app = new APIGatewayResolver({
  enableValidation: true,
});

const todoSchema = z.object({
  userId: z.number(),
  title: z.string(),
  completed: z.boolean()
});

app.post('/todo', async ({ title, userId, completed }) => {
  // TODO: create todo

  return true;
}, {
  validation: {
    input: todoSchema,
    output: z.boolean()
  }
});

We will automatically parse and validate the outer envelope of the event according to the resolver you are using, so that you can focus on providing the schema for the body only.

Enabling SwaggerUI

Since Event Handler supports OpenAPI, you can use SwaggerUI to visualize and interact with your API.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver({
  enableValidation: true,
});

app.enableSwagger({
  path: '/swagger',
});

TODO: routes w/ validation

export const handler = async (event, context) =>
  app.resolve(event, context);

We will implement this feature as a complete opt-in feature and with as little overhead as possible. Because of this we will return the HTML needed to render the SwaggerUI but you will have to bundle your own swagger-ui-bundle.min.js together with your function or provide an url to a CDN-hosted version of it (i.e. this).

Accessing request details

Event Handler exposes the resolver request and Lambda context under convenient properties like: app.currentEvent and app.lambdaContext, this is why you see app.resolve(event, context) in every example.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import type { APIGatewayProxyEvent, Context } from 'aws-lambda';

const app = new APIGatewayResolver();

app.route('/todos/', () => {
  const event: APIGatewayProxyEvent = app.currentEvent; // event
  const context: Context = app.lambdaContext; // context
  
  return {
    todo: await todos.json(),
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Handling not found routes

By default, we return 404 for any unmatched route.

You can use the notFound() method or class method decorator to override this behavior, and return a custom response.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();
const app = new APIGatewayResolver();

app.notFound(async (error: Error) => {
  logger.info('Not found route', { path: app.currentEvent.path });
  return {
    statusCode: 302,
    headers: {
      Location: '/login'
    }
  }    
});

class Lambda {
  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

Handling methods not allowed

By default, we return 405 for any request that matches a route but is using a method with no resolver.

You can use the methodNotAllowed() method or class method decorator to override this behavior, and return a custom response.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();
const app = new APIGatewayResolver();

app.methodNotAllowed(async (error: Error) => {
  logger.info('Method not allowed', {
    path: app.currentEvent.path,
    method: app.currentEvent.method,
  });

  return {
    statusCode: 403,
  }    
});

class Lambda {
  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

Error handling

To keep your route handlers as focused as possible, you can use the errorHandler() method or class method decorator with any Error class or children. This allows you to handle common errors outside of your route, for example validation errors.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();
const app = new APIGatewayResolver();

class Lambda {
  @app.errorHandler(ZodError)
  public async handleInvalidRequest(error: ZodError) {
    logger.error('Malformed request', {
      path: app.currentEvent.path,
    });
    
    return {
      statusCode: 400,
      headers: {
        'Content-Type': 'text/plain',
      },
      body: 'Invalid request parameters.'
    }
  }

  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

The errorHandler() method also supports passing a list of error classes you want to handle with a single handler.

Internally, we’ll test the error being thrown using error instanceof YourError first, and then error.name === YourError.name, this allows us to ensure equality even when the imports or the bundle might be polluted with double imports.

Raising HTTP errors

You can easily raise any HTTP Error back to the client using one of the handy prebuilt error responses. This ensures your Lambda function doesn’t fail but return the correct HTTP response signalling the error.

We provide pre-defined errors for the most popular ones such as HTTP 400, 401, 404, 500, etc.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import {
  BadRequestError,
  InternalServerError,
  NotFoundError,
  ServiceError,
  UnauthorizedError,
} from '@aws-lambda-powertools/event-handler/errors';

const app = new APIGatewayResolver();

app.get('/bad-request-error', () => {
  throw BadRequestError('Missing required parameter'); // HTTP 400
});

app.get('/unauthorized-error', () => {
  throw UnauthorizedError('Unauthorized'); // HTTP 401
});

app.get('/not-found-error', () => {
  throw NotFoundError(); // HTTP 404
});

app.get('/interanal-server-error', () => {
  throw InternalServerError('Internal server error'); // HTTP 500
});

app.get('/service-error', () => {
  throw ServiceError('Something went wrong!', { code: 502 }); // HTTP 502
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Custom Domain API Mappings

When using the Custom Domain API Mappings feature in Amazon API Gateway, you must use the stripPrefixes parameter in the APIGatewayRestResolver constructor.

Scenario: You have a custom domain api.mydomain.dev. Then you set a /payment mapping to forward any payment requests to your Payments API.

Challenge: This means you path value for any API requests will always contain /payment/<actual_request>, leading to HTTP 404 as Event Handler is trying to match what’s after payment/. This gets further complicated with an arbitrary level of nesting.

Solution: To address this, we use the stripPrefixes parameter to remove these prefixes before trying to match the routes you defined in your application.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver({
  stripPrefixes: ['/payment']
});

/**
 * Handles this:
 * {
 *   "resource": "/subscriptions/{subscription}",
 *   "path": "/payment/subscriptions/123",
 *   "httpMethod": "GET"
 * }
*/
app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

After removing a path prefix with stripPrefixes, the new root path will automatically be mapped to the path argument of /.

For example. when using the stripPrefixes value of /pay, there is no difference between a request path of /pay and /pay/; and the path argument would be defined as just /.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

/**
 * This will support:
 * /v1/dev/subscriptions/<subscription>
 * /v1/stg/subscriptions/<subscription>
 * /v1/qa/subscriptions/<subscription>
 * /v2/dev/subscriptions/<subscription>
*/
const app = new APIGatewayResolver({
  stripPrefixes: [new RegExp(/\/v[1-3]+\/(dev|stg|qa)/)]
});

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Advanced use cases

CORS

You can configure CORS in each resolver constructor via the cors parameter with a CORSConfig class.

This will ensure that CORS headers are returned as part of the response when your functions match the path invoked and the Origin matches one of the allowed values.

Optionally, you can disable CORS on a per path basis with the cors: false option.

Pre-flight

Pre-flight (OPTIONS) calls are typically handled by API Gateway or Lambda Function URL. For ALB instead, you are expected to handle these requests yourself.

For convenience, we automatically handle them for you as long as you enable CORS in the constructor.

Defaults

For convenience, these are the default values when using CORSConfig to enable CORS:

Key	Value	Note
allowOrigin	*	Only use the default value for development. Never use * for production unless your use case strictly requires it
extraOrigins	[]	Additional origins to be allowed, in addition to the one specified in allowOrigin
allowHeaders	["Authorization", "Content-Type", "X-Amz-Date", "X-Api-Key", "Amz-Security-Token"]	Additional headers that will be appended to the default list for your convenience
exposeHeaders	[]	Any additional header beyond the safe ones listed by the CORS specification
maxAge	``	Only for pre-flight requests if you choose to have your function handle it instead of API Gateway
allowCredentials	false	Only necessary when working with cookies, authorization headers, or TLS client certificates

Compress

You can compress with gzip and base64 encode your responses via the compress parameter. You have the option to pass the compress parameter when working with a specific route.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
}, {
  compress: true,
});

export const handler = async (event, context) =>
  app.resolve(event, context);

The client must send the Accept-Encoding header, otherwise we will send a normal response.

Binary responses

For convenience, we automatically base64 encode binary responses. You can also use in combination with compress parameter if your client supports gzip.

Similar to the compress feature, the client must send the Accept header with the correct media type.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/logo', async () => {
  TODO: response object
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Notes:

• Lambda Function URLs handle binary media types automatically
• Amazon API Gateway does not support the */* binary media type when CORS is also configured

Debug mode

You can enable debug mode via the POWERTOOLS_DEV or POWERTOOLS_EVENT_HANDLER_DEBUG environment variables.

This will enable full traceback errors in the response, log any request and response, and set CORS to allow any origin (*).

Since this might reveal sensitive information in your logs and relax CORS restrictions, we recommend you to use this only for local development and as sparingly as possible.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
});

export const handler = async (event, context) =>
  app.resolve(event, context);

OpenAPI

When you enable data validation, we use a combination of standard-schema compatible schemas (Zod, Valibot, Arktypes) and OpenAPI type annotations to add constraints to your API's parameters.

In OpenAPI documentation tools like SwaggerUI, these annotations become readable descriptions, offering a self-explanatory API interface. This reduces boilerplate code while improving functionality and enabling auto-documentation.

Customizing OpenAPI parameters

Whenever you use OpenAPI parameters to validate query strings or path parameters, you can enhance validation and OpenAPI documentation by using any of these parameters:

Field name	Type	Description
alias	string	Alternative name for a field, used when serializing and deserializing data
validation_alias	string	Alternative name for a field during validation (but not serialization)
serialization_alias	string	Alternative name for a field during serialization (but not during validation)
description	string	Human-readable description
gt	number	Greater than. If set, value must be greater than this. Only applicable to numbers
ge	number	Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers
lt	number	Less than. If set, value must be less than this. Only applicable to numbers
le	number	Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers
min_length	number	Minimum length for strings
max_length	number	Maximum length for strings
pattern	string	A regular expression that the string must match.
strict	boolean	If true, strict validation is applied to the field. See Strict Mode for details
multiple_of	number	Value must be a multiple of this. Only applicable to numbers
allow_inf_nan	boolean	Allow inf, -inf, nan. Only applicable to numbers
max_digits	number	Maximum number of allow digits for strings
decimal_places	number	Maximum number of decimal places allowed for numbers
examples	Array	List of examples of the field
deprecated	boolean	Marks the field as deprecated
include_in_schema	boolean	If false the field will not be part of the exported OpenAPI schema
json_schema_extra	JsonDict	Any additional JSON schema data for the schema property

Customizing API operations

Customize your API endpoints by adding metadata to endpoint definitions.

Here's a breakdown of various customizable fields:

Field Name	Type	Description
summary	string	A concise overview of the main functionality of the endpoint. This brief introduction is usually displayed in autogenerated API documentation and helps consumers quickly understand what the endpoint does.
description	string	A more detailed explanation of the endpoint, which can include information about the operation's behavior, including side effects, error states, and other operational guidelines.
responses	Record<number, Record<string, OpenAPIResponse>>	A dictionary that maps each HTTP status code to a Response Object as defined by the OpenAPI Specification. This allows you to describe expected responses, including default or error messages, and their corresponding schemas or models for different status codes.
response_description	str	Provides the default textual description of the response sent by the endpoint when the operation is successful. It is intended to give a human-readable understanding of the result.
tags	Array	Tags are a way to categorize and group endpoints within the API documentation. They can help organize the operations by resources or other heuristic.
operation_id	string	A unique identifier for the operation, which can be used for referencing this operation in documentation or code. This ID must be unique across all operations described in the API.
include_in_schema	boolean	A boolean value that determines whether or not this operation should be included in the OpenAPI schema. Setting it to False can hide the endpoint from generated documentation and schema exports, which might be useful for private or experimental endpoints.
deprecated	boolean	A boolean value that determines whether or not this operation should be marked as deprecated in the OpenAPI schema.

To implement these customizations, include extra parameters when defining your routes:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
}, {
  openApi: {
    summary: 'Retrieves a subscription',
    description: 'Loads a subscription identified by a `subscriptionId`',
    responseDescription: 'The subscription object',
    responses: {
      200: { description: 'subscription found' },
      404: { description: 'subscription not found' }
    },
    tags: ['Subscription']
  }
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Split routes with Router

As you grow the number of routes a given Lambda function should handle, it is natural to either break into smaller Lambda functions, or split routes into separate files to ease maintenance - that's where the Router feature is useful.

Let's assume you have index.ts as your Lambda function entrypoint and routes in todos.ts. This is how you'd use the Router feature.

todos.ts

import { Router } from '@aws-lambda-powertools/event-handler';

const todosRouter = new Router();

todosRouter.get('/todos/', () => {
  const headers = todosRouter.currentEvent.headers; // currentEvent is available on the router
  const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
  return {
    todo: await todos.json(),
  };
});

export { todosRouter };

index.ts

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { todosRouter } from './todos.js';

const app = new APIGatewayResolver();
app.includeRouter({ router: todosRouter });

export const handler = async (event, context) =>
  app.resolve(event, context);

Route prefix

When necessary, you can set a prefix when including a router object. This means you could remove /todos prefix altogether.

todos.ts

import { Router } from '@aws-lambda-powertools/event-handler';

const todosRouter = new Router();

todosRouter.get('/', () => {
  const headers = todosRouter.currentEvent.headers; // currentEvent is available on the router
  const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
  return {
    todo: await todos.json(),
  };
});

export { todosRouter };

index.ts

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { todosRouter } from './todos.js';

const app = new APIGatewayResolver();
app.includeRouter({ router: todosRouter, prefix: '/todos' });

export const handler = async (event, context) =>
  app.resolve(event, context);

Specialized routers

You can use specialized router classes according to the type of event that you are resolving. This way you'll get type hints from your IDE as you access the currentEvent property.

Router	Resolver	curentEvent type
APIGatewayRouter	APIGatewayRestResolver	APIGatewayProxyEvent
APIGatewayHttpRouter	APIGatewayHttpResolver	APIGatewayProxyEventV2
LambdaFunctionUrlRouter	LambdaFunctionUrlResolver	LambdaFunctionUrlEvent

Sharing contextual data

You can use appendContext when you want to share data between your App and Router instances. Any data you share will be available via the context object available in your App or Router context.

We always clear data available in context after each invocation.

index.ts

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { todosRouter } from './todos.js';

const app = new APIGatewayResolver();
app.includeRouter({ router: todosRouter, prefix: '/todos' });

export const handler = async (event, context) =>
  app.appendContext({ isAdmin: true });
  app.resolve(event, context);

import { Router } from '@aws-lambda-powertools/event-handler';

const todosRouter = new Router();

todosRouter.get('/', () => {
  const { isAdmin } = router.context;
  const headers = todosRouter.currentEvent.headers; // currentEvent is available on the router
  const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
  return {
    todo: await todos.json(),
  };
});

export { todosRouter };

Out of scope

The following items are to be considered out of scope for the first iteration of the feature:

• ALBResolver - Resolver for Amazon Application Load Balancer (ALB)
• VPCLatticeResolver - Resolver for Amazon VPC Lattice
• Middy.js compatible middleware
• Middleware engine for routes
• Custom serializers for responses

If you are interested in any of them and would like us to prioritize them right after the first version, please let us know under this RFC.

Potential challenges

TBD

Dependencies and Integrations

No response

Alternative solutions

N/A

Acknowledgment

• This RFC meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[leandrodamascena]

Since this is a high-level definition of the implementation and features, I have nothing to add other than adding a head method here:

You can use named methods to specify the HTTP method that should be handled in your functions. That is, app.<http_method>, where the HTTP method could be get(), post(), put(), patch(), delete().

Congrats on writing this RFC @dreamorosi! It's going to be the most anticipated utility for Typescript Powertools for this year.

[jlweston]

Looks fab and I can't wait to start using this for real to replace a less elegant solution we currently have in place!

Could I get clarification on a couple of bits?

• If a Middy middleware is out of scope for the first version, can we simply pass a 'Middyfied' handler to a resolver/router and still benefit from both Middy and this event handler?
• What does the SwaggerUI generation look like when using routers to split a larger app into smaller lambdas? Does only the code necessary for SwaggerUI end up in the lambda that called app.enableSwagger, with each other lambda containing only the business logic bound to their routes?

[dreamorosi]

Thank you for taking the time to read and for the feedback!

Let me address both your questions:

If a Middy middleware is out of scope for the first version, can we simply pass a 'Middyfied' handler to a resolver/router and still benefit from both Middy and this event handler?

The main usage we see for Middy.js is wrapping your function handler rather than specific arbitrary functions. This is because among other things, Middy.js middlewares expect a certain function signature that includes the event and context payloads.

Since method resolvers will need to have a specific signature that allows Event Handler to pass down the request info, I don't think it'll be possible to wrap a resolver specifically. You should however be able to do something like this and have Middy.js "upstream"

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { middy } from '@middy/core';

const app = new APIGatewayResolver();

app.get('/todos', async () => {
  // handle route
});

export const handler = middy(async (event, context) =>
  app.resolve(event, context))
  .use(...); // your middlewares go here

The main disclaimer here is that any middlewares you add should not manipulate the event, otherwise we can't guarantee that the resolver & router will work correctly. So, for example you should be able to use other Powertools for AWS middlewares like the Logger, Metrics, and Tracer ones - but most likely not some of the Middy.js ones that normalize the event and/or modify headers and such.

Our view for this feature, and part of the reason why we're not including Middy.js for now, is that using the Event Handler should make redundant using many/all of the Middy.js middlewares related to request handling, since these responsibilities will be covered by the resolver.

Even for Powertools for AWS Middy.js middlewares related to logging, metrics, tracing, and idempotency we might consider a deeper integration with Event Handler that would allow to do things like flush your metrics, inject request context in your logs, or trace a route a the resolver level. To explain what I mean a pseudo-code example:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { Metrics, MetricUnit } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics();
const app = new APIGatewayResolver();
app.useMetrics(metrics);

app.get('/bookings', async () => {
  TODO: response object

  metrics.addMetric('booking-requested', MetricUnit.Count, 1); // this is flushed automatically when the route handler returns.
});

export const handler = async (event, context) =>
  app.resolve(event, context);

Note that the example above is not final, and it's also not part of the initial scope of the implementation. Something that instead will be supported from day one is mixing and matching class method decorators, so you would be able to do this:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

import { Tracer } from '@aws-lambda-powertools/tracer';

const tracer = new Tracer();
const app = new APIGatewayResolver();
app.useTracer(tracer);

class Lambda {
  @app.errorHandler(ZodError)
  public async handleInvalidRequest(error: ZodError) {
    logger.error('Malformed request', {
      path: app.currentEvent.path,
    });
    
    return {
      statusCode: 400,
      headers: {
        'Content-Type': 'text/plain',
      },
      body: 'Invalid request parameters.'
    }
  }

  @tracer.traceMethod({ name: '/todos/:todoId' }) // this would create a span for your request & annotate it
  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

With that said, I'd like to also better understand the request of combining Middy.js middlewares with this feature, if there's something missing we might want to address it.

---

What does the SwaggerUI generation look like when using routers to split a larger app into smaller lambdas? Does only the code necessary for SwaggerUI end up in the lambda that called app.enableSwagger, with each other lambda containing only the business logic bound to their routes?

Yes, the SwaggerUI will work only at the function level, so the OpenAPI schema will include only the routes from a single lambda function.

This is the same behavior we have in the Powertools for AWS Lambda (Python) version - but if there's demand for it in the future, we might also research if it's possible to stitch together schemas & UIs from multiple Lambda functions (I don't know if it's possible on top of my head).

[jlweston]

Appreciate the detailed response.

You should however be able to do something like this and have Middy.js "upstream"

This sounds perfectly workable. We already use a factory function that accepts a lambda handler as a callback and returns a Middyfied handler, so we'd just adapt what's being passed in.

Our view for this feature, and part of the reason why we're not including Middy.js for now, is that using the Event Handler should make redundant using many/all of the Middy.js middlewares related to request handling, since these responsibilities will be covered by the resolver.

Even for Powertools for AWS Middy.js middlewares related to logging, metrics, tracing, and idempotency we might consider a deeper integration with Event Handler that would allow to do things like flush your metrics, inject request context in your logs, or trace a route a the resolver level.

Between the routing, input/output validation and error handling, you definitely look to be covering most of the functionality our team use Middy for day-to-day. I can almost see us skipping Middy entirely, even with only the items in your initial scope.

Yes, the SwaggerUI will work only at the function level, so the OpenAPI schema will include only the routes from a single lambda function.

Documenting our split lambdas is a pain point for us at the moment. We're using a Serverless Framework plugin to associate OpenAPI docs with endpoints but it's way more verbose and repetitive than we'd like. Being able to generate a single SwaggerUI page for many lambdas using your proposed syntax would be a massive DX improvement for us but I reckon we can have a separate step in our CI/CD pipeline to stitch them together if needed. Here's hoping others show interest too 🤞

Looking forward to this arriving! Great work!

[svozza]

Is there a reason that APIGatewayResolver doesn't use the new keyword but Router does?

const app = APIGatewayResolver();

const todosRouter = new Router();

Personally, I prefer factory functions that don't use new but we shoul probably be consistent either way.

If you need to accept multiple HTTP methods in a single function, or support a custom HTTP method for which no method exists (e.g. TRACE), you can use the route() method and pass an array of HTTP methods.

Am I missing something but I don't see a route() method, I see an object with a field called method:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = APIGatewayResolver();

app.post('/todos/', () => {
  const data = JSON.parse(app.currentEvent.body || '{}');
  const todos = await fetch(`https://jsonplaceholder.typicode.com/todos`, {
    body: JSON.stringify(data),
  });
  
  return {
    todo: await todos.json(),
  };
}, {
  method: ['PUT', 'POST'] // <= http methods
});

On another point, it seems a bit strange to me that the name of the method here is app.post when it accepts more than one verb. I feel like you could easily miss the method object down the bottom with the HTTP verbs especially for a complex function. I would favour a method name that makes clear that this route accepts multiple HTTP verbs, maybe app.any or something.

Also, what happens if some someone does this:

app.post('/todos/', () => {
 // ...
}, {
  method: ['PUT', 'POST']
});

app.post('/todos/', () => {
 // ...
}, {
  method: ['POST']
});

Which POST method wins?

[leandrodamascena]

On another point, it seems a bit strange to me that the name of the method here is app.post when it accepts more than one verb. I feel like you could easily miss the method object down the bottom with the HTTP verbs especially for a complex function. I would favour a method name that makes clear that this route accepts multiple HTTP verbs, maybe app.any or something.

Also, what happens if some someone does this:

app.post('/todos/', () => {
 // ...
}, {
  method: ['PUT', 'POST']
});

app.post('/todos/', () => {
 // ...
}, {
  method: ['POST']
});

Which POST method wins?

I think it was a typo, it should be app.route. Assuming that all post, get, head and other methods are an abstraction of app.route, this example should be app.route and build the routes based on the HTTP verb informed in method parameter.

[dreamorosi]

Yes it was a typo, good catch - it should be app.route, like you mentioned it doesn't make sense to accept multiple methods when you're already using a verb-specific method.

Regarding this:

Is there a reason that APIGatewayResolver doesn't use the new keyword but Router does?

No, that was also a typo - both should have the new keyword. This is the convention we use throughout the rest of utilities.

I'll fix both of them - thank you again for taking the time to read the RFC and engage, Stefano!

[wparad]

Bloat

I think the enableSwagger should be removed. It is unnecessary bloat for the library to be able to handle that and will actively make us to not use this library and continue using our the openapi-factory, hono, or middy.

APIGW

It also isn't clear if the routes in api gateway /top-level/{proxy+} will correctly get resolved to the more specific routes defined in this library. Historically that has been a problem when in API we have something like /top-level/{proxy+}, but in lambda we have /top-level/:resource/sub/:other and the parameters resource and other are not populated correctly.

APIGW ANY Support

I didn't see any callout for APIGW ANY, is this going to be supported automatically, or are we going to have to know about it? For instance, if we want a route agnostic handler, is that possible?

405 Method Not Allowed

How will this be supported? How will we know that the method isn't allowed, in some frameworks we need to have brittle duplicated code that contains the same list of supported methods in order to report the 405, and then duplicate this in every router. The framework we are using right now automatically generates 405s for us without any complexity.

Authorizers

I didn't see any support for custom lambda authorizers which almost always are necessary for us

v2 HTTP APIs

We heavily rely upon v2 HTTP APIs and not REST APIs, is this RFC meant for both or only specifically the v1 REST APIs?

Access to the templated path

It wasn't clear if we need to access metadata about the powertools routed event how we would do that. the 405s issue is one of them, another one is getting both resolved path as well as the unresolved path template, often we might want to log the template. We don't want to have to duplicate the template from the router in our code, and instead should be able to do request.route to get this value.

Middlewares

We absolutely need a way to intercept all requests:

• Before the router handler is run
• After the router handler is run
• On Error from route handler or one of the two previous handlers

Integration with Express, Hono, Middy, etc...

How exactly can we use this to debug a running HTTP version of our service? Is there some way to export the stored data so that it can be injected into these HTTP frameworks? I don't expect understanding of these frameworks or even an integration, but rather, a method like api.getCompiledRoutes() which could return a list/map of all the registered routes.

[dreamorosi]

Hi @wparad, thanks for taking the time to read the RFC and leave comments.

Let me answer to each one of your points in random order:

API Gateway HTTP (v2)

We heavily rely upon v2 HTTP APIs and not REST APIs, is this RFC meant for both or only specifically the v1 REST APIs?

From the second paragraph at the top of the RFC:

While the code samples in the RFC will use mainly APIGatewayRestResolver, the first iteration of the feature will have in scope also the APIGatewayHttpResolver and LambdaFunctionUrlResolver resolvers.

In that sentence, APIGatewayHttpResolver refers to API Gateway v2 or otherwise known as HTTP. Thanks for pointing out that it might be unclear, I'll update that sentence to clarify.

Custom AWS Lambda Authorizers

I didn't see any support for custom lambda authorizers which almost always are necessary for us

API Gateway calls authorizers before forwarding the request to your Lambda proxy integrations. Because of this, at least in its current form Event Handler can't influence the logic of the custom authorizer itself and by the time a request arrives it's assumed to be authorized.

When it comes to parsing a request we already have Parser with built-in schemas specific to custom Lambda authorizers.

But if you had something different in mind, I'd still like to hear your thoughts on how Event Handler could help in this area. We might not include it in the first couple iterations of the feature, but if it's compelling enough and there's demand we can add it to the backlog still.

API Gateway route with method ANY

I didn't see any callout for APIGW ANY, is this going to be supported automatically, or are we going to have to know about it? For instance, if we want a route agnostic handler, is that possible?

Setting a route method mapping as ANY in API Gateway is a way of instructing the service to forward requests to your Lambda function Proxy integration regardless of the actual HTTP verb present in the request.

Once the request reaches the function, and is processed by Event Handler we'll look at the HTTP verb present in the request and call your resolvers accordingly. So, yes, ANY will be supported.

With that said, I would not necessarily recommend you using ANY unless necessary and instead take the time to apply the proper mapping between route, methods, and integrations. By doing this you can save on both costs and latency since API Gateway will bounce any request for methods not mapped as 403 and never call your function.

For ALB & most likely Lambda Function URLs, all requests of all methods get routed to the integration.

405 Method Not Allowed

Thank you for pointing out this gap. Today handling this case even in Powertools for AWS Lambda (Python) can be tricky, so we decided to include a new method that will help with this. By default we'll return 405 when a route is matched but the method is not allowed by any resolver you defined. Plus there will be a method that allows you to customize this behavior with your own logic.

This is the new section I added to the RFC, and will open an issue on the Python repo shortly:

---

By default, we return 405 for any request that matches a route but is using a method with no resolver.

You can use the methodNotAllowed() method or class method decorator to override this behavior, and return a custom response.

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';
import { Logger } from '@aws-lambda-powertools/logger';

const logger = new Logger();
const app = new APIGatewayResolver();

app.methodNotAllowed(async (error: Error) => {
  logger.info('Method not allowed', {
    path: app.currentEvent.path,
    method: app.currentEvent.method,
  });

  return {
    statusCode: 403,
  }    
});

class Lambda {
  @app.get('/todos/:todoId')
  public async getTodoById({ params }) {
    const { todoId } = params;
    const todos = await fetch(`https://jsonplaceholder.typicode.com/todos/${todoId}`);
    
    return { todos: await todos.json() }
  }
}

export const handler = async (event, context) =>
  app.resolve(event, context);

---

Access to the templated path

If I understand correctly your question, you want to be able to access the raw request fields. If this is the case, then the answer is already covered in the "Accessing request details" section.

To recap, you'll be able to access the raw request and Lambda context respectively with app.currentEvent and app.lambdaContext, which you can call in your resolvers. The currentEvent one will include the entire request payload as it arrived to the Lambda function.

If instead this was not what you meant, please elaborate and clarify.

enableSwagger

This is a completely opt-in feature, and when enabled we will automatically generate a couple of routes that return an HTML page for the Swagger UI.

From the code perspective, the HTML and resolver code needed to generate these routes takes about 8kb unminified if we use the Python implementation as reference (here & here).

While I would not call this bloat, we'll do our best to expose this code in a way that can be tree-shaken by bundlers, for example by exposing it via subpath module - something we do quite extensively in this project.

For what concerns the actual JavaScript needed to render & make the Swagger UI function (i.e. this - 1.2MB), I can confirm that we have no plan of adding it to our library and thus to your bundles.

We'll make this configurable so that customers who want to enable the Swagger UI will either need to bundle that file with their code or provide a full url of a CDN where that file is hosted. This way customers who don't want / need this feature won't have any overhead in their bundle.

Thank you for calling out this detail, your question made us look at the topic more closely and decide to implement it this way. I'll add some of the details above to the RFC.

Middlewares

We absolutely need a way to intercept all requests [...]

We understand completely that middlewares are a critical part of many production-ready APIs. Because of this we want to make sure we create a solid middleware engine that is flexible enough but also offers a good DX. For this reason middlewares are not part of the initial scope but will be instead part of a subsequent launch shortly after GA.

The features marked as in scope in the RFC above are what will be available on day 1 of release, this doesn't mean we won't continue investing and improving the feature set. For middlewares specifically, we'll most likely add them right after GA, but we will share more accurate timelines at a later date.

This is the current plan, but if there's enough demand we are also open to reconsider the scope and include them.

If you have any feedback / comment / or idea about middlewares feel free to leave them here anyway.

Routing

It also isn't clear if the routes in api gateway /top-level/{proxy+} will correctly get resolved to the more specific routes defined in this library. Historically that has been a problem when in API we have something like /top-level/{proxy+}, but in lambda we have /top-level/:resource/sub/:other and the parameters resource and other are not populated correctly.

We haven't settled yet on any routing algorithm in particular but personally I'm leaning towards having both a regex-based one and a trie-tree one, just like Hono.

When it comes to route specificity, if you have for example two route handlers for /top-level/:resource and /top-level, and the request has /top-level/1 the most specific one - /top-level/:resource - will be called.

For the prefix part, this is somewhat covered in the "Custom Domain API Mappings". You'll be able to specify a shared prefix for your resolver so that you don't have to write /top-level in all your route handlers.

If instead this was not what you meant, and you were referring to something else, please elaborate and clarify.

Local testing

As you mentioned, we don't expect to integrate directly with other frameworks like Hono or Express. When it comes to Middy.js we might have some integration as long as Middy.js is used in a way that doesn't manipulate the incoming request. I touched upon the topic in this other comment.

The part of your question that I am more interested is the one about the local debugging & testing:

How exactly can we use this to debug a running HTTP version of our service? Is there some way to export the stored data so that it can be injected into these HTTP frameworks? I don't expect understanding of these frameworks or even an integration, but rather, a method like api.getCompiledRoutes() which could return a list/map of all the registered routes.

Since we are not standing up any HTTP server nor listening on any socket/port there's no need to actually run your code in a separate process and make requests to it.

If you want to debug or test code that involves Event Handler you should treat this as any other function/module that you export and consume from another file/module.

For example, you might have your main entry point that looks like this:

// your imports & routes go here

export const handler = async (event, context) =>
  app.resolve(event, context);

You can then from other files import handler and call it as you see fit, both with a debugger session attached or with tests. For the sake of the example, you'd write a test like this:

import { it, expect } from 'vitest';
import type { Context } from 'aws-lambda';
import { handler } from './index.ts';

it('handles a GET request', async () => {
  // Prepare
  const event = {
    // ... rest of the API Gateway REST | API Gateway HTTP  | ALB | Function URL payload
    path: '/hello',
    method: 'GET'
  };
  const context: Context = { ... } // context object

  // Act
  const response = await handler(event, context);

  // Assess
  expect(response.statusCode).toEqual(200);
  // ... other assertions go here
});

This is true for any other function you write for Lambda, you don't necessarily need to expose it as a web server to test/debug it. If instead we're talking about emulating IAM permissions, the Lambda execution environment, or other aspects of AWS then this is out of scope for Powertools for AWS. Although you could probably use things like SAM or LocalStack.

---

I hope I have answered most/all your questions. Thank you again for your inputs.

[wparad]

Thank you for clarifying these. Let me dive into the specific points:

Access to the templated path

If I understand correctly your question, you want to be able to access the raw request fields. If this is the case, then the answer is already covered in the "Accessing request details" section.

Actually no. The Lambda raw request fields will come from APIGW which only include the following:

• APIGW matched route
• Full path

Let's take the example of a route like: /top/:top_id/sub/:sub_id. If our APIGW is defined as ANY /{proxy+}, then the event sent to Lambda has the two properties:

• apigw route: /{proxy+}
• full path: top/resolve-top-id-001/sub/resolve-sub-id

But we need explicitly /top/:top_id/sub/:sub_id which does not exist in the original request, it only exists in the configuration for the framework itself. Thus we want the framework to expose this data back to us.

enableSwagger

I was explicitly talking about the framework code to enable swagger, not what it pulls in. 8kb or even 4kb, more is still more. As long as it is exposed as a subpath that can somehow be ignored without requiring us to trust our bundling tools to tree shake it, that's good by me.

Local testing

If you want to debug or test code that involves Event Handler you should treat this as any other function/module that you export and consume from another file/module.

I think I wasn't clear here. I would want convert locally our lambda into an HTTP server. Right now we do that by wrapping the lambda library and passing that into Express. The original Lambda-Express library for nodejs did this, SAM does this. The use case is "I want a localhost running http service on my machine that I can hit with payloads that look exactly like the payloads sent to apigateway or lambda function url and for those to converted into requests that are sent to our registered endpoint.

Sure we can test the endpoints explicitly with unit tests, but I'm not sure it would work exactly correctly otherwise.

For example, we can't just use something like this:

express.any('.*', (params, etc..) => {
  const event = {
    // ... rest of the API Gateway REST | API Gateway HTTP  | ALB | Function URL payload
    path: params.path,
    method: params.method,
    ...
  };
  const context: Context = { ... } // context object

  // Act
  const response = await handler(event, context);

  // convert back to express result;
 return convertFromLambdaResponseBackToExpressResult(response);
}

The problem is that perfectly constructing the event object, not that it matches lambda, but that it matches exactly how api gateway would convert an HTTP request into those properties for lambda is the challenge.

Middlewares

The features marked as in scope in the RFC above are what will be available on day 1 of release, this doesn't mean we won't continue investing and improving the feature set. For middlewares specifically, we'll most likely add them right after GA, but we will share more accurate timelines at a later date.

Ah it wasn't clear to me that "out of scope" means "not right now" and not "no plans to implement".

[perpil]

One feature I like about lambda-api is the method based middleware. I use it to attach jwt validation to certain routes and to annotate metrics/traces with things I pick out of the request that might be shared across routes. When you think about middleware, if you allow us to attach it to routes as well that will be much appreciated.

[martzmakes]

I appreciate the effort behind this RFC, but I strongly disagree with the lambdalith approach it seems to promote. Consolidating multiple routes with distinct Swagger specs into a single Lambda goes against serverless best practices and introduces significant operational and security challenges.

Key Concerns:
1. Cold Starts & Performance: Bundling multiple routes into one Lambda increases deployment package size and initialization time, making cold starts longer and more impactful. While this may reduce the frequency of cold starts (it might not because of the increased throughput/concurrent executions), the cost of each one becomes significantly higher, ultimately degrading user experience.
2. Security Risks: Smaller Lambdas enable least-privileged access, ensuring each function only has the permissions it truly needs (e.g., read-only vs. write). A lambdalith must grant broad permissions to cover all routes, creating unnecessary attack surface and increasing the risk of privilege escalation.
3. Separation of Concerns: Small, single-purpose functions are easier to debug, test, and deploy independently. A lambdalith couples unrelated functionality, making it harder to isolate issues and increasing the blast radius of changes or errors.
4. Observability: Metrics, logs, and traces are clearer when each Lambda serves a single purpose. In a lambdalith, understanding performance bottlenecks or debugging errors becomes a complex, noisy task.

While lambdaliths may appear to simplify routing, allow for the ability of having a better-defined OpenAPI spec and reduce cold starts, the trade-offs in performance, security, and maintainability outweigh the benefits. Serverless succeeds because of its modularity and principle of least privilege. Let’s focus on patterns that enhance these strengths rather than undermine them.

Would love to hear others’ thoughts on maintaining best practices while achieving the goals this RFC targets.

[dreamorosi]

Thank you for taking the time to read the RFC and engage with it.

AWS best practices tend to favor single-purpose Lambda functions for many of the reasons you listed as well as others, if possible customers should go this route, especially when building new complex workloads and/or when rearchitecting existing ones.

In practice, like everything in engineering, there are tradeoffs and many customers still need or prefer to use a single (or few) Lambda functions to handle multiple API routes. Having one function per route is the best option, but many customers might not be able to take on the operational complexity that this brings either because they lack resources to do so.

There are tons of customers who are either just starting their Serverless journey and might be more familiar with this pattern, this type of feature is for these customers and serves as an on-ramp to start getting some of the benefits of Lambda without having to tackle too many things at once. Likewise, sometimes workloads are just not complex enough to warrant splitting them, or in other cases there might be other requirements that force the single function pattern.

One of the core tenets of Powertools for AWS Lambda is to be progressive, meaning that our utilities are designed to be incrementally adoptable for customers at any stage of their Serverless journey. This is a clear example of that.

Our position on the topic is not to promote this as the one and only way to go, but to acknowledge that many customers still want to work this way and thus help them do it in the best way possible.

Both on GitHub and during offline interactions this is and has been our most requested feature, and while we can talk about best practices as much, sometimes customers just want to get the job done. This is us acknowledging this and helping them to do it with a good DX and as securely as possible, despite the inherent tradeoffs of this pattern that we already list prominently in our documentation.

[leandrodamascena]

Hey @martzmakes thanks for bringing to us your point of view and concerns, we really value this and this is the main propose of an RFC.

I appreciate the effort behind this RFC, but I strongly disagree with the lambdalith approach it seems to promote.

In this RFC, we are proposing a new experience for developers when creating APIs using AWS Lambda and Powertools TypeScript. This new utility will allow customers to manage routes, access event parameters, handle routes not found, handle unauthorized methods, facilitate the use of CORS, auto-serialize responses, data validation and, among other things, also facilitate the generation of OpenAPI. So this utility will allow customers to choose between the best architecture they want: lambdalith, micro-Lambda or another name that eventually emerges.

While we recognize that in this first version of this utility the customer will not be able to create OpenAPI Schema when using several Lambda functions at the same time, but this is on our radar and will be implemented at some point in the future. In case of this is mandatory for your workload, for example, there is still the option of exporting the OpenAPI from the Amazon API Gateway console as a workaround.

All the features we have developed over the years at Powertools have been improved by listening to our customers, and this case will be no different. For this reason, I find it hard to say that we are suggesting any type of bad practices because 1 - out of 10? - feature needs to be improved in the next versions of this utility.

Serverless succeeds because of its modularity and principle of least privilege. Let’s focus on patterns that enhance these strengths rather than undermine them.

I think that Serverless computing's success can be attributed to several key factors. Primarily, it significantly reduces operational overhead for customers. Its ability to rapidly scale resources based on demand, coupled with low complexity, contributes greatly to its popularity. And yes, security and isolation is another thing that contributes a lot.

For me, one of the most appealing aspects of running serverless workloads is its flexibility. It not only allows for single-responsibility Lambda functions but also enables you to organize functions by business domains, workload components, or any other logical division that aligns with your business needs, security requirements and architectural design.

Would love to hear others’ thoughts on maintaining best practices while achieving the goals this RFC targets.

I believe we're on the right track with this RFC. We're offering an optimized experience for AWS Lambda while still allowing customers to choose their preferred approach.

Although the initial release won't include OpenAPI Schema support for multiple Lambda functions, I had an idea: once we launch, you could help us enhance this OpenAPI feature, potentially unlocking new use cases. I'd love to hear your thoughts on this. I'm also available on the CB Slack if you'd like to discuss further.

Again, thanks for engaging with this RFC and helping us to make it even better.

[wparad]

👏

[walmsles]

Would love to hear others’ thoughts on maintaining best practices while achieving the goals this RFC targets.

"To LambdaLith" or "Not to Lambdalith" is the eternal question. I agree with your sentiments in regards to modularity, security, etc being best practices. Powertools EventHandlers can still be used in a "micro" sense by defining a single route. Doing this you still get all the benefits of reduced boilerplate for CORS, data validation, serialization etc etc that Powertools provides and still have a consistent, repeatable pattern for creating micro lambda functions for APIs (if that is your choice). Using EVentHandler will also enable the same implementation to pivot to the different ways of hosting APIs on AWS - RestV1, RestV2, functionUrl, ALB, etc etc (all the API things), which is a great benefit that python delivers today and assume future work would expand the resolvers for the varying flavours of API you can host on AWS.

Powertools is not enabling or encouraging specific architectures, however it is driven by where customers are today so needs to cater for a variety of different use-cases. Right now lambdaliths are a popular mechanism of removing Operational burden and being an initial stepping stone to serverless which enables the strangler pattern or other evolutionary pathways to be applied in moving APIs to more granular modules where it is relevant and required.

I feel your concerns can be addressed within the documentation itself where Powertools can highlight design choices or different architectural patterns. AWS Lambda Powertools for python has a considerations section covering the different use-cases and trade-offs which I feel is a good way to cover off your concerns.

[walmsles]

I also like this conversation between Yan Cui and Heitor Lessa - it's about allowing teams to move fast with thier current skills and knowledge. I feel the whole Monolith vs singular functions is something that can never be resolved because every use-case is different and in architecture there are always considerations that go beyond the technology choices to make them work effectively and in a cost efficient way. When I say "cost efficient", I am not talking about Lambda cost specifically but about how teams are structured, how they work and how they deploy which takes into consideration Organisational decisions or choices that are non-negotiable and these always exist.

[scratchclaggy]

For the Open API section where you detail customizing parameters: is the intention that each of those parameters will be top level attributes to the config object? I worry that there's quite a few parameters, and as the Open API spec changes you might open yourself up to name collisions. Thoughts on scoping the customizations to an attribute like openApi or similar?

Awesome work with the RFC, keen to see what's next. Will there be much opportunity for community contributions to this work?

[leandrodamascena]

Hi @scratchclaggy! Thanks for sharing this. Can you please expand a bit more on your question here? Are you specifically talking about data validation properties like min_length, min_length and others that are Model properties (zod and others) or the arguments sent in the route like responses, summary and others?

Will there be much opportunity for community contributions to this work?

Everything we do is public and we will open issues as soon as we have the final decision on this RFC. @dreamorosi will lead the implementation, and of course all help from the community is welcome, after all, working with our community is part of our DNA.

[dreamorosi]

Thank you for the question, and for engaging with the RFC.

If I understand the question correctly, you're probably referring to this section:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
}, {
  summary: 'Retrieves a subscription',
  description: 'Loads a subscription identified by a `subscriptionId`',
  responseDescription: 'The subscription object',
  responses: {
    200: { description: 'subscription found' },
    404: { description: 'subscription not found' }
  },
  tags: ['Subscription']
});

export const handler = async (event, context) =>
  app.resolve(event, context);

If this is the case, I agree with your point and we should instead change the signature to this:

import { APIGatewayResolver } from '@aws-lambda-powertools/event-handler/resolvers';

const app = new APIGatewayResolver();

app.get('/subscription/:subscriptionId', async ({ params }) => {
  return {
    subscriptionId: params.subscriptionId,
  };
}, {
  openapi: { // <--- Now it's namespaced/nested
    summary: 'Retrieves a subscription',
    description: 'Loads a subscription identified by a `subscriptionId`',
    responseDescription: 'The subscription object',
    responses: {
      200: { description: 'subscription found' },
      404: { description: 'subscription not found' }
    },
    tags: ['Subscription']
  }
});

export const handler = async (event, context) =>
  app.resolve(event, context);

This way the implementation is more future-proof and like you said, easier to avoid name collisions. Coincidentally, it'll also very slightly simplify the internal implementation since we can now check a specific property in the options object.

I'll get the RFC updated in the next couple hours to reflect this.

---

Will there be much opportunity for community contributions to this work?

Like @leandrodamascena mentioned, we want to make this as contributor-friendly as possible.

My plan for this is to leave the RFC open for ~a couple more weeks and then create a backlog of issues for the work to be done. I'll label issues based on whether they're open for contribution and/or whether they're good first issues. These labels will help to convey what is up for grabs and they're there mainly to help guide the implementation and make sure things are implemented in the right order/pace.

I expect to pick up some of the first more foundational items to set the structure of the utility and its patterns, but after that as the implementation progressed I'll be happy to dedicate time to reviewing community PRs as they come in.

Looking forward to seeing a PR from you when the time comes!

[scratchclaggy]

Awesome, yes that's exactly what I was referring to. I'll keep an eye out once this goes through, looking forward to getting in there!

[TastefulElk]

Hey @dreamorosi and team! Love the effort here - well-written, structured, thought through - fantastic work as always!

Can you expand a little on the proposal to access currentEvent from the app outside the handler? I'd expect to access the request from a parameter in the callback, not from global state that will carry over between invocations. I guess technically as long as it's properly reset it's not really a problem per se, it just feels a little unnatural to me.

I.e. current

[...]
const app = new APIGatewayResolver();

app.get('/search', () => {
  const query = app.currentEvent.query('q');

  const { limit, offset } = app.currentEvent.query();

  return {
    message: 'Hello, World!'
  };
});
[...]

vs something like

[...]
const app = new APIGatewayResolver();

app.get('/search', ({ currentEvent }) => {
  const query = currentEvent.query('q');

  const { limit, offset } = currentEvent.query();

  return {
    message: 'Hello, World!'
  };
});
[...]

[TastefulElk]

I'm just struggling to see where the global approach would be beneficial enough to warrant the tradeof of a (to me) unexpected design.

This model, besides aligning with the Powertools for AWS Lambda (Python) implementation

I get and sympathize with this, but customers (I'm guessing) rarely have experience from both Powertools for Python AND Typescript, instead they'd typically have experience from other tools like express and hono.

For the todo example, I don't really see when it would be good in a scenario like that to create a depedencny on the http router instead of taking it in as a parameter. I think, as @leandrodamascena mentions, that getting it as a paratemer instead would simplify testing and make the code more intuitive and decoupled.

There's definitely some merit to the idea that this is made specifically for Lambda though, and that it's good to challenge some concepts in similar tools that are meant to be used in the wider ecosysystem.

[wparad]

Anything global will immediately break as soon as it is wrapped in anything that allows parallel processing. Sure Lambda itself might not allow that, but every other tool out there, will allow it, Hono, Express, Jest, Mocha, Vitest, etc... None of these will understand that. Having this be global is just a terrible idea and only going to cause concrete problems.

It's much better to create a "Pit of Success". Just because "Python" does it doesn't mean it should be copied here. And having "two different strategies" to make this happen also creates confusion. This should just be fixed. Fundamentally it should be a function parameter, and if someone really wants a global thing, they can just wrap the powertools function handler. However, if this library gets it wrong and makes it global, there is no fixing that.

[dreamorosi]

Thanks everyone for chiming in, you're right.

I'm gonna update the RFC to make this a function parameter instead of a property of the router/resolver itself. It makes more sense, so I'm happy to diverge here.

---

As a side note, just to acknowledge this point:

I get and sympathize with this, but customers (I'm guessing) rarely have experience from both Powertools for Python AND Typescript, instead they'd typically have experience from other tools like express and hono.

While true that customers in one ecosystem are generally more familiar with tools from it, we are seeing more and more companies of a certain size asking us to increase consistency wherever possible because they want to standardize their operations and have multiple teams using similar tools. In practice we're seeing teams writing either of these languages wanting to adopt Powertools and expect to have a similar DX.

With that said, this specific instance is not one where we should enforce standardization and we should instead go for the better option, which is clearly using function parameters.

Thank you for bringing this up and creating this thread - very useful!

(I'll get the RFC updated in the next couple hrs - bear with me while I reply to other threads).

[dreamorosi]

While I was updating the RFC I came up with a doubt, I'd appreciate your inputs on it.

Right now the object you can destructure as first parameter in your route resolver is meant to include path parameters that will have the same name as your actual path parameter (except for camel case normalization), for example:

[...]
const app = new APIGatewayResolver();

app.get('/todo/:todoId', ({ todoId }) => {

  return {
    message: 'Hello, World!'
  };
});
[...]

With this in mind, how do we avoid a collision between our currentEvent & currentContext parameters and a potential parameter that might have these terms in the path? i.e.

[...]
const app = new APIGatewayResolver();

app.get('/todo/current_event', ({ currentEvent }) => {

  return {
    message: 'Hello, World!'
  };
});
[...]

As far as I know, we don't have any way of preventing this from happening so I am not sure how to handle this.

The first option I thought would be to namespace these parameters within the object, like:

[...]
const app = new APIGatewayResolver();

app.get('/todo/:todoId', ({ todoId, aws }) => {
  const query = aws.event.query('q');
  return {
    message: 'Hello, World!'
  };
});
[...]

the second one would be to use a second parameter entirely:

[...]
const app = new APIGatewayResolver();

app.get('/todo/:todoId', ({ todoId }, { event }) => {
  const query = event.query('q');
  return {
    message: 'Hello, World!'
  };
});
[...]

Personally I would prefer the first option since it seems cleaner but there's still a risk of name collisions if you have aws in your path. The second one is safer but requires a more crowded signature.

What are your thoughts?

[TastefulElk]

couldn't they too be added to the "new" request object? Something like:

app.get('/todo/:todoId', (request) => {
  const query = request.query('q');
  const todoId = request.params.todoId // or event.params("todoId")
  return {
    message: 'Hello, World!'
  };
});

[aviv-akhansari]

What would be the advantages of having this while libraries like Hono for Lambda already do that very well?

[dreamorosi]

This is covered in the "Use Case" section of the original post, but it boils down to the fact that customers who are either already on Lambda or already using Powertools for AWS have been asking us to add this feature for the past two years.

This is because despite many other frameworks available they would prefer something specifically designed to work on AWS Lambda and maintained by AWS.

We don't expect everyone to move from Express, Hono, Fastify, or others if they're already happy with the framework they have. Our utilities are modular, so you can continue enjoying other features and don't have to adopt this one if other solutions are working better for your workload.