Serverless .NET: Building Minimal APIs with .NET 8 on AWS Lambda

For years, building APIs in .NET meant working with the structured, controller-based approach of MVC and Web API. With the introduction of Minimal APIs in .NET 6 and their refinement in .NET 8, developers now have a more lightweight, concise, and performance-oriented way to build HTTP services. This is a perfect match for serverless platforms like AWS Lambda, where cold start times and memory footprint are critical.

This guide demonstrates how to build a serverless API using .NET 8's Minimal APIs and deploy it to AWS Lambda with API Gateway.

Why Minimal APIs for Serverless?

• Lower Boilerplate: Minimal APIs do away with the ceremony of controllers, Startup.cs, and complex configuration. Your entire API can be defined in a single file, making it easier to read and maintain.
• Faster Cold Starts: With a streamlined pipeline and fewer dependencies to load, Minimal APIs can lead to faster cold start times compared to their traditional counterparts.
• Performance: The framework is highly optimized for performance, making it an excellent choice for latency-sensitive serverless applications.

Step 1: Create the .NET Minimal API Project

First, you'll need the Amazon.Lambda.Templates package to get started. If you don't have it, install it using the .NET CLI:

dotnet new -i Amazon.Lambda.Templates

Now, create a new project using the "Serverless API" template:

dotnet new serverless.MinimalAPI -n MyServerlessApi
cd MyServerlessApi

This template scaffolds a new project that is pre-configured for deployment to AWS Lambda. It includes:

• A Program.cs file with a basic Minimal API.
• A LambdaEntryPoint.cs class that translates API Gateway events into HTTP requests that the API can understand.
• A serverless.template file, which is a CloudFormation template for deploying your API.

Step 2: Define Your API Endpoints

Open the Program.cs file. This is where you'll define your API's routes and handlers. The template provides a few examples, but let's create a simple endpoint to fetch a product.

// In Program.cs

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Add AWS Lambda support.
builder.Services.AddAWSLambdaHosting(LambdaEventSource.HttpApi);

var app = builder.Build();

app.MapGet("/products/{id}", (string id) => 
{
    // In a real application, you would fetch this from a database.
    var product = new Product(id, "My Awesome Product", 99.99);
    return Results.Ok(product);
});

app.Run();

public record Product(string Id, string Name, double Price);

• AddAWSLambdaHosting(LambdaEventSource.HttpApi): This crucial line adds the necessary services to bridge the gap between Lambda and the ASP.NET Core runtime.
• app.MapGet(): This is the core of Minimal APIs. We're mapping an HTTP GET request for /products/{id} to a simple lambda handler that creates and returns a Product record.

Step 3: Deploy to AWS Lambda

The easiest way to deploy the project is using the AWS Toolkit for Visual Studio or the .NET Global Tool for Lambda.

Let's use the command-line tool.

1. Install the Deployment Tool:

   dotnet tool install -g Amazon.Lambda.Tools
   

2. Deploy the API: Navigate to your project's directory and run the deploy command:

   dotnet lambda deploy-serverless
   

   The tool will prompt you for a CloudFormation stack name. It then packages your application, uploads it to S3, and deploys the CloudFormation template (serverless.template). This template provisions:

   • An AWS Lambda function for your code.
   • An API Gateway (HTTP API) to act as the public endpoint.
   • The necessary IAM roles and permissions.

Once the deployment is complete, the tool will output the URL of your new serverless API.

Step 4: Test Your API

You can now make a request to your new endpoint using a tool like curl or Postman:

curl https://<your-api-id>.execute-api.<region>.amazonaws.com/products/prod-123

The API will invoke your Lambda function, which will execute your Minimal API handler and return the product data:

{
  "id": "prod-123",
  "name": "My Awesome Product",
  "price": 99.99
}

Conclusion

.NET 8's Minimal APIs are a game-changer for building serverless applications on AWS. They provide a modern, lightweight, and high-performance alternative to traditional controller-based APIs, making them an ideal choice for the serverless world.

By combining the concise syntax of Minimal APIs with the power of AWS Lambda, you can build and deploy powerful, scalable, and cost-effective .NET services with less code and less ceremony than ever before.