Building Scalable APIs with C# and .NET 8

An End-to-End Guide to Structuring, Securing, and Deploying High-Performance APIs Using Modern C#.

.NET 8 isn’t just faster — it’s smarter. And with C# 12, building a scalable, production-ready REST API has never felt this clean.

In this guide, I’ll walk you through how I architect scalable APIs using .NET 8, Entity Framework Core, dependency injection, middleware, JWT-based authentication, and minimal APIs. Each section has one large code block and no fluff.

1. Project Setup with Minimal API

Forget bloated controllers — .NET 8 makes Minimal APIs first-class. Here’s how I scaffold my projects now:

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Add services
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Swagger
app.UseSwagger();
app.UseSwaggerUI();

// Routes
app.MapGet("/ping", () => Results.Ok("Pong!"));

app.Run();

✅ No controllers, no ceremony — just endpoints. Great for microservices.

2. Connecting to a Database Using EF Core

Add a database context and register it via dependency injection.

// AppDbContext.cs
public class AppDbContext : DbContext
{
    public DbSet<User> Users => Set<User>();

    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
}

public class User
{
    public int Id { get; set; }
    public string Email { get; set; } = string.Empty;
}

// Program.cs (continued)
builder.Services.AddDbContext<AppDbContext>(opt =>
    opt.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

✅ Now you can inject AppDbContext anywhere — and yes, .NET 8 supports connection pooling natively.

3. Creating API Endpoints for CRUD Operations

Here’s how I expose a user service with full CRUD, all inside Program.cs for simplicity.

app.MapPost("/users", async (User user, AppDbContext db) =>
{
    db.Users.Add(user);
    await db.SaveChangesAsync();
    return Results.Created($"/users/{user.Id}", user);
});

app.MapGet("/users", async (AppDbContext db) =>
    await db.Users.ToListAsync());

app.MapGet("/users/{id}", async (int id, AppDbContext db) =>
    await db.Users.FindAsync(id) is User user ? Results.Ok(user) : Results.NotFound());

app.MapPut("/users/{id}", async (int id, User input, AppDbContext db) =>
{
    var user = await db.Users.FindAsync(id);
    if (user is null) return Results.NotFound();

    user.Email = input.Email;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/users/{id}", async (int id, AppDbContext db) =>
{
    var user = await db.Users.FindAsync(id);
    if (user is null) return Results.NotFound();

    db.Users.Remove(user);
    await db.SaveChangesAsync();
    return Results.NoContent();
});

✅ Notice the lack of ceremony. Business logic stays clean and testable.

4. Adding JWT Authentication

For real-world APIs, you need auth. Here’s a clean way to do JWT-based login and authorization.

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(opt =>
    {
        opt.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = "myapi",
            ValidAudience = "myapi-client",
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes("supersecurekey123456789"))
        };
    });

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/secure", [Authorize] () => Results.Ok("This is secured!"));

✅ Protect any endpoint with [Authorize]. You can also scope it per role or policy.

5. Structuring for Scale with Services and DI

Separate concerns using services and interfaces. Inject them where needed.

// IUserService.cs
public interface IUserService
{
    Task<User?> GetByIdAsync(int id);
}

// UserService.cs
public class UserService : IUserService
{
    private readonly AppDbContext _db;
    public UserService(AppDbContext db) => _db = db;

    public async Task<User?> GetByIdAsync(int id) => await _db.Users.FindAsync(id);
}

builder.Services.AddScoped<IUserService, UserService>();

app.MapGet("/user-details/{id}", async (int id, IUserService userService) =>
{
    var user = await userService.GetByIdAsync(id);
    return user is not null ? Results.Ok(user) : Results.NotFound();
});

✅ Keeps Program.cs readable and your business logic testable.

6. Global Exception Handling with Middleware

Catch unhandled exceptions and return consistent error messages.

app.Use(async (context, next) =>
{
    try
    {
        await next.Invoke();
    }
    catch (Exception ex)
    {
        context.Response.StatusCode = 500;
        await context.Response.WriteAsJsonAsync(new { error = ex.Message });
    }
});

✅ No need to wrap every endpoint with try-catch.

7. Pagination and Filtering Support

For scalable APIs, support pagination by default.

app.MapGet("/paginated-users", async (int page = 1, int size = 10, AppDbContext db) =>
{
    var users = await db.Users
        .Skip((page - 1) * size)
        .Take(size)
        .ToListAsync();

    return Results.Ok(users);
});

✅ Let clients control load — no 5000-row responses.

8. Deploying to Azure App Service or AWS Lambda

.NET 8 supports native AOT and lightweight Docker images. Here’s how to containerize.

# Dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApi.dll"]

# Build and run
docker build -t myapi .
docker run -p 5000:80 myapi

✅ Ready for Azure Container Apps, ECS, or Fargate.

Final Thoughts

.NET 8 with C# 12 changes the API game:

• Minimal APIs give you clarity and performance
• EF Core makes DB operations intuitive
• Middleware + DI + JWT handles the real-world boilerplate
• Docker + AOT makes deployment frictionless

This stack powers production APIs for startups and enterprises alike — clean, scalable, and fast.

If you want to see a complete GitHub repo for this structure (CI/CD + Terraform + Swagger), I’m happy to share that too. Let’s build clean APIs.