Docs: add Request object usage to middleware documentation

[leandrodamascena]

What were you searching in the docs?

PR #8036 introduced a Request object that gives middleware and route handlers access to the resolved route pattern, path parameters, method, headers, query parameters, and body.

The current middleware docs only show app.current_event for accessing request data. This works for headers, body, and raw event, but app.current_event.path_parameters returns the API Gateway path parameters (e.g. {proxy+}), not the Powertools-resolved ones.

app.request solves this and is a cleaner pattern overall.

Is this related to an existing documentation section?

No response

How can we improve?

1. Update docs/core/event_handler/api_gateway.md middleware section to show app.request usage alongside app.current_event

2. Add a new example file showing middleware with app.request:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Request, Response
from aws_lambda_powertools.event_handler.middlewares import NextMiddleware

def auth_middleware(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response:
    req = app.request
    route = req.route              # "/users/{user_id}"
    method = req.method            # "GET"
    path_params = req.path_parameters  # {"user_id": "123"}

    # auth logic here...
    return next_middleware(app)

3. Add a new example showing handler injection via type annotation:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Request

app = APIGatewayRestResolver()

@app.get("/users/<user_id>")
def get_user(user_id: str, request: Request):
    user_agent = request.headers.get("user-agent")
    return {"id": user_id, "user_agent": user_agent}

4. Add a note clarifying when to use app.request vs app.current_event:

   • app.request.path_parameters - Powertools-resolved parameters (e.g. {"user_id": "123"})
   • app.current_event.path_parameters - API Gateway raw parameters (e.g. {"proxy": "users/123"})
   • app.request is available after route resolution (middleware and handlers)
   • app.current_event is available from the start of the request

5. Update existing examples in examples/event_handler_rest/src/middleware_*.py to mention app.request where relevant

Got a suggestion in mind?

No response

Acknowledgment

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