AwsLambda.Host.Envelopes.ApiGateway 1.2.1

AwsLambda.Host.Envelopes.ApiGateway

Strongly-typed API Gateway event handling for the AwsLambda.Host framework.

Overview

This package provides strongly-typed envelopes for handling API Gateway events in Lambda functions. It contains classes that can be used as input and output types for Lambda functions that process REST APIs, HTTP APIs (payload format 1.0), WebSocket APIs, HTTP APIs (payload format 2.0), and Lambda Function URLs.

The envelopes extend the base APIGatewayProxyRequest, APIGatewayProxyResponse, and HTTP API equivalents with strongly-typed BodyContent properties for easier request/response serialization:

Quick Start

Define your request and response types, then create a handler:

using System;
using System.Collections.Generic;
using AwsLambda.Host.Builder;
using AwsLambda.Host.Envelopes.ApiGateway;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = LambdaApplication.CreateBuilder();
var lambda = builder.Build();

// ApiGatewayRequestEnvelope<Request> provides the API Gateway event with deserialized request body
// ApiGatewayResponseEnvelope<Response> wraps the response and serializes it to the body
lambda.MapHandler(
    ([Event] ApiGatewayRequestEnvelope<Request> request, ILogger<Program> logger) =>
    {
        logger.LogInformation("Request: {Name}", request.BodyContent?.Name);

        return new ApiGatewayResponseEnvelope<Response>
        {
            BodyContent = new Response($"Hello {request.BodyContent?.Name}!", DateTime.UtcNow),
            StatusCode = 200,
            Headers = new Dictionary<string, string> { ["Content-Type"] = "application/json" },
        };
    }
);

await lambda.RunAsync();

// Your request and response payloads
internal record Request(string Name);

internal record Response(string Message, DateTime TimestampUtc);

For HTTP API v2, use ApiGatewayV2RequestEnvelope<T> and ApiGatewayV2ResponseEnvelope<T> in the same way.

Custom Envelopes

To implement custom deserialization logic, extend the appropriate base class and override the payload handling method:

// Example: Custom XML deserialization for requests
public sealed class XmlApiGatewayXmlRequestEnvelope<T> : ApiGatewayRequestEnvelopeBase<T>
{
    public override void ExtractPayload(EnvelopeOptions options)
    {
        using var stringReader = new StringReader(Body);
        using var xmlReader = XmlReader.Create(stringReader, options.XmlReaderSettings);
        var serializer = new XmlSerializer(typeof(T));
        BodyContent = (T)serializer.Deserialize(xmlReader)!;
    }
}

// Example: Custom XML serialization for responses
public sealed class XmlApiGatewayXmlResponseEnvelope<T> : ApiGatewayResponseEnvelopeBase<T>
{
    public override void PackPayload(EnvelopeOptions options)
    {
        using var stringWriter = new StringWriter();
        using var xmlWriter = XmlWriter.Create(stringWriter, options.XmlWriterSettings);
        var serializer = new XmlSerializer(typeof(T));
        serializer.Serialize(xmlWriter, BodyContent);
        Body = stringWriter.ToString();
    }
}

This pattern allows you to support multiple serialization formats while maintaining the same envelope interface.

AOT Support

When using .NET Native AOT, register all envelope and payload types in your JsonSerializerContext:

[JsonSerializable(typeof(ApiGatewayRequestEnvelope<Request>))]
[JsonSerializable(typeof(ApiGatewayResponseEnvelope<Response>))]
[JsonSerializable(typeof(Request))]
[JsonSerializable(typeof(Response))]
internal partial class SerializerContext : JsonSerializerContext;

Register the serializer and configure envelope options to use the context:

builder.Services.AddLambdaSerializerWithContext<SerializerContext>();

builder.Services.ConfigureEnvelopeOptions(options =>
{
    options.JsonOptions.TypeInfoResolver = SerializerContext.Default;
});

Other Packages

Additional packages in the aws-lambda-host framework for abstractions, observability, and event source handling.

Package	NuGet	Downloads
AwsLambda.Host
AwsLambda.Host.Abstractions
AwsLambda.Host.OpenTelemetry
AwsLambda.Host.Envelopes.Sqs
AwsLambda.Host.Envelopes.ApiGateway
AwsLambda.Host.Envelopes.Sns
AwsLambda.Host.Envelopes.Kinesis
AwsLambda.Host.Envelopes.KinesisFirehose
AwsLambda.Host.Envelopes.Kafka
AwsLambda.Host.Envelopes.CloudWatchLogs
AwsLambda.Host.Envelopes.Alb

License

This project is licensed under the MIT License. See LICENSE for details.