More full examples of the micro function pattern

[beck3905]

What were you initially searching for in the docs?

I am new to powertools and have been reading the docs to determine how to integrate it into my existing projects. My project use the micro function pattern for API Gateway. All of the API Gateway code examples and discussion are more relevant to the monolith pattern. There is the discussion of monolith vs micro function, but no actual code examples for the micro function pattern.

For example, with the micro function pattern would one still use the ApiGatewayResolver when there is only one route? Or would one use the @event_source decorator approach instead?

Is this related to an existing part of the documentation? Please share a link
https://awslabs.github.io/aws-lambda-powertools-python/latest/core/event_handler/api_gateway/#considerations
https://awslabs.github.io/aws-lambda-powertools-python/latest/core/event_handler/api_gateway/
https://awslabs.github.io/aws-lambda-powertools-python/latest/utilities/data_classes/#api-gateway-proxy

Describe how we could make it clearer
Please add more examples for the micro function pattern. Please add more details about when you would use the ApiGatewayResolver vs the event_source decorator or if you would ever use both together.

If you have a proposed update, please share it here

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.

[heitorlessa]

Hey Brian, absolutely, it’s on our radar - I’d like us to provide a SAM CLI / Cookiecutter template where you could choose between micro or monolithic deployment. Until we get there, you can totally use ApiGatewayResolver even if it’s for a single route - I personally did that in a project yesterday. We’re releasing exception handling for any status code and custom exception for ApiGatewayResolver in the next release (either tomorrow or Monday the latest) — this comes in handy whether you have a micro or monolithic deployment. If you have ideas or areas you find challenging with micro functions, please leave them in the comments as we could use them to make a good opinionated sample.

…

On Thu, 16 Dec 2021 at 18:08, boring-cyborg[bot] ***@***.***> wrote: Thanks for opening your first issue here! We'll come back to you as soon as we can. — Reply to this email directly, view it on GitHub <#902 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBCQN5CA3GKRMSQ72FLURIMJ7ANCNFSM5KG2TVMQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[beck3905]

@heitorlessa Thanks for your response. Is there a simple way to handle translation of input and output for Api Gateway Proxy events without having to use the whole router? For a microfunction I don't really need the router capabilities.

[heitorlessa]

I'd still advise to use the Event Handler for API Gateway - you'd be surprised by the amount of intricacies on input/output, serialization, 404, CORS (if used), binary (if used).

For context: Historically, we created Event Source Data Classes first as most micro functions only needed the Input from API Gateway event and its variations, until more customers started to hit other corners like path parameters, or wanting to easily switch between API Gateway and ALB and AppSync (to an extent), or even non-Lambda like Fargate -- for the latter, it's a no brainier to move to something like Flask/FastAPI or simply keep API Gateway Resolver if ALB is fronting it.

Without knowing much about your use case, here's what I did yesterday with a customer for a single route and function:

import base64

from aws_lambda_powertools import Logger, Metrics, Tracer
from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.utilities.typing import LambdaContext

tracer = Tracer()
logger = Logger()
metrics = Metrics()
app = ApiGatewayResolver()


@app.post("/trip")
@tracer.capture_method
def ingest_trip_route():
    """Handles `/trip` POST method to ingest trip onto S3/SQS

    Returns
    -------
    response: dict
        Successful message on trip upload and receipt containing
        storage filename + enqueued message identifier

        **Example**

        ```python
        {
            "message": "trip successfully uploaded",
            "receipt":"5c6d96c4ca8748b59ff82dc0d0cfd37f+fake-message-receipt-id"
        }
        ```
    """
    trip_payload: str = app.current_event.body
    trip_archive: bytes = base64.b64decode(trip_payload)
    ...

    return { 
        "message": "trip successfully uploaded",
        "receipt": f"{storage_filename}+{enqueued_message_id}"
    }


@metrics.log_metrics(capture_cold_start_metric=True)
@tracer.capture_lambda_handler
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
def lambda_handler(event, context: LambdaContext):
    """Lambda Handler for all routes defined in API Gateway

    Parameters
    ----------
    event: dict
        API Gateway raw event
    context: LambdaContext
        Lambda Context

    Returns
    -------
    response: dict
        API Gateway Proxy response

        **Example**

        ```python
        {
            'statusCode': 200,
            'body': {
                "message": "trip successfully uploaded",
                "receipt":"5c6d96c4ca8748b59ff82dc0d0cfd37f+fake-message-receipt-id"
            },
            'headers': {'Content-Type': 'application/json'}
            'isBase64Encoded' False
        }
        ```
    """
    try:
        return app.resolve(event, context)
    except Exception as e:
        logger.exception(e)
        raise

We also allow any regex for the route in case you wanna do a catch all style. Today's release will allow multiple HTTP Methods for a single route too.

PS: Thank you for joining us on Slack!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.