Docs: Event Handler REST

[dreamorosi]

What were you searching in the docs?

As we approach the first experimental release of Event Handler, we need to add a dedicated documentation page for the features implemented so far.

Is this related to an existing documentation section?

No response

How can we improve?

We should have a page similar to this, but for our implementation of Event Handler.

Got a suggestion in mind?

No response

Acknowledgment

• I understand the final update might be different from my proposed suggestion, or refused.

[dcabib]

Hey! 👋

Just took a look at the REST Event Handler implementation and the existing docs structure. I notice REST isn't in the main event-handler index yet (makes sense since it's still experimental). Here's what I'm thinking:

Current observations:

Looking at how AppSync Events, GraphQL, and Bedrock docs are structured, they all follow a nice pattern:

• Key Features upfront
• Terminology section
• Getting Started with required resources
• Usage examples with actual code
• Advanced section for the deeper stuff

The REST handler is currently tucked away in api-gateway.md with the "Don't use in production (yet)" warning, but the implementation looks pretty solid in /packages/event-handler/src/rest/.

What we could start with:

1. Add REST to the main Event Handler index

Once it's ready, add it alongside the other handlers with something like:

- __REST API__
    ---
    Event Handler for API Gateway REST/HTTP APIs, ALB, Function URLs, and VPC Lattice. 
    Build lightweight REST APIs without the boilerplate.
    
    [:octicons-arrow-right-24: Read more](./rest.md)

2. Create example snippets

I noticed /examples/snippets/event-handler/rest/ doesn't exist yet. We'll need those for the docs to work properly. Maybe start with:

• Basic CRUD example
• CORS setup
• Error handling
• Parser integration

3. Follow the existing doc pattern

Looking at how AppSync and Bedrock docs are structured, a REST doc could have:

// Quick example in "Getting Started"
import { ApiGatewayEventHandler } from '@aws-lambda-powertools/event-handler/rest';

const app = new ApiGatewayEventHandler();

app.get('/users/:id', async (event) => {
  const { id } = event.pathParameters;
  return {
    statusCode: 200,
    body: { userId: id }
  };
});

export const handler = app.resolve;

4. The unique REST challenges

What makes REST different from the other handlers:

• Multiple event sources (API Gateway vs ALB vs Function URLs)
• Different path parameter styles
• CORS complexity
• Binary responses

Maybe a comparison table showing what works where?

Questions before we dive deeper:

1. Import path: Should it be @aws-lambda-powertools/event-handler/rest or something else?

2. Class naming: I see BaseRouter in the code - what's the public-facing class name going to be? RestEventHandler? ApiGatewayEventHandler?

3. Examples priority: What examples would be most helpful first? Basic CRUD? Auth patterns? File uploads?

4. Event source focus: Should we document all sources equally or focus on API Gateway first?

Small wins to start:

Maybe we could:

1. Create a basic /examples/snippets/event-handler/rest/ directory with a simple example
2. Update the warning message in api-gateway.md to point to the GitHub discussion
3. Start collecting common use cases from the community

What do you think? Happy to help with any of these pieces! 🚀

[dreamorosi]

Hi @dcabib, thank you for the comment.

There are still a few areas that need to be addressed before we can work on this item, which is why its status is "On hold" and the issue is marked as blocked by #4393.

With that said, we try to keep issues as self-contained as possible so many of these decisions will need to happen in dedicated discussions/issues while this issue should focus exclusively on documenting what's already been implemented.

Still, let me address some of the points in your comment:

Add REST to the main Event Handler index

I agree that we should add it, but the description you suggested is not accurate nor is the relative link in the code snippet. The feature currently works only with API Gateway REST and the file is called api-gateway.md as you mentioned earlier in your comment.

Create example snippets

I agree that we should create code snippets, however these should exist to serve what's in the documentation - not the other way around.

Basic CRUD example

We'll most likely want to show how to use the resolver to create route resolver, but the docs are not the place for a full CRUD example.

CORS setup

The feature is currently not implemented, so it wouldn't make sense to add it yet.

Error handling

Agreed.

Parser integration

We don't have this feature implemented yet, so we can't add it to the docs.

Follow the existing doc pattern

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

const app = new ApiGatewayEventHandler();

app.get('/users/:id', async (event) => {
 const { id } = event.pathParameters;
 return {
   statusCode: 200,
   body: { userId: id }
 };
});

export const handler = app.resolve;

This code snippet is incorrect:

• ApiGatewayEventHandler we don't have this class, and if we follow the pattern in the Python version of Powertools for AWS we'll likely call it something like APIGatewayRestResolver - however this is not decided and it shouldn't be a decision taken in this documentation issue
• the signature of the resolver doesn't match what we're actually implementing - it should be async ({ id }) => {} and we don't have any pathParameters in the current implementation

The unique REST challenges

We don't support any of the features listed (yet), and currently we support only one kind of path parameter which is the one you included in the code snippet above - which other ones are there?

Regarding the other questions you listed, as I mentioned we don't have these answers yet.

---

I appreciate the enthusiasm and offer to help, however this issue is not yet ready to be worked on.

If you're still interested in contributing, please check back next week - once #4393 is implemented we'll need to add most of the features you mentioned that are still missing and we could definitely use some help.

Additionally, early next week I'll also try opening some new issues for other areas that we have in the pipeline, so you could contribute there.

[dcabib]

I will be happy to help...

[eyal-converge]

Any plans for this doc the be released soon ?
As we are debating internally between TS/python

[dreamorosi]

We're still working on #4393 which is blocking this issue.

Our current plan is to have that implementation ready by the end of this week and release the Event Handler as experimental - together with the docs - in the next release (next Tuesday). However plans might change and we might end up releasing it in the following one (aka in 2.5 weeks).

If you want to see how the utility will look like, while we work on the docs you can check the RFC for this feature which has code examples of all the features in scope.

We're really keen on you picking this version of Powertools for AWS over the Python version, so if there's anything we can do to sway your decision we're here for it!

If you have any questions about specific features feel free to ask, we're happy to answer here or even jump on a call to discuss your use case - email us at aws-powertools-maintainers@amazon.com and we can set this up.

[eyal-converge]

Thanks for the detailed response. The RFC looks well-structured and covers a lot of ground.
When you mention it’s experimental, how reliable would you consider it for production use?

Our main use cases involve dynamic routes and middlewares, alongside an APIGW + Cognito auth setup.
For example: Webapp -> APIGW -> Cognito auth -> Lambda (with easy access to auth context)

[dreamorosi]

The experimental label primarily refers to the fact that the API surface (i.e. properties, method names, behavior) might change between the experimental release and the general availability date without notice nor a major version bump.

While we are confident with the implementation and don't release any untested code, a secondary goal of the experimental period is to work with early adopters to identify paper cuts and potential bugs that might've slipped in.

In case of issues during this period, we're also keen to work on fixes promptly and even do ad-hoc or nightly releases if it makes sense and would unblock customers such as you.

All in all, barring major issues, we don't expect the experimental period to extend beyond November.

[eyal-converge]

Got it — we’d be more than happy to try it out as soon as possible and compare it with the Python equivalent.
What’s the best way to get started given that the documentation hasn’t been updated yet?

[dreamorosi]

Amazing!

Besides the docs and #4393 mentioned above, we'll still need to make the utility available in the exports of the package.json. In practice, at the moment you're not going to be able to import the utility in your project. As mentioned, this should change on Tuesday next week.

Besides this, if you decide to push through with the testing, we'd really appreciate it if you could send us an email at the address I shared above using your work email - this is optional and only for us to have a contact in case we need to reach out to share major bugs or issues reported by other customers during the experimental period.

[eyal-converge]

Thanks! We’ll keep a close eye on the issue and the official docs.
I’ve also sent you an email from my work address.

[powertools-for-aws-oss-automation]

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under v2.26.0 version!