O que é Minimal API

De forma simples e direta, podemos dizer que as Minimal APIs são uma forma simplificada de expor endpoints HTTP no ASP.NET Core, introduzidas no .NET 6, que eliminam grande parte da infraestrutura tradicional de Controllers, Actions, Filters e Attributes.

Minimal API não é um "atalho", e um modelo diferente

Um erro comum é enxergar Minimal API como apenas um MVC simplificado. Conceitualmente, ela é outra abordagem:

• Controllers são abstrações baseadas em convenção
• Minimal API é configuração explícita de endpoints

Isso muda a responsabilidade do desenvolvedor:

• Menos “mágica”
• Mais controle consciente do pipeline HTTP

Em Minimal API, cada endpoint é essencialmente uma função HTTP pura, registrada diretamente no host.

Em vez de:

• Controllers
• [HttpGet], [Route]
• Herança de ControllerBase
• Model binding via atributos

Endpoint como unidade de comportamento

No modelo tradicional, o comportamento é espalhado:

• Controller
• Action
• Filters
• Attributes

Na Minimal API, o endpoint passa a ser a unidade mínima de comportamento HTTP:

• Entrada (model binding)
• Dependências (DI)
• Autorização
• Resultado

Isso favorece:

• Coesão
• Leitura direta do contrato HTTP
• Facilidade de refatoração

Você define endpoints diretamente no Program.cs (ou em módulos), usando delegates fortemente tipados.

Qual problema o Minimal API resolve

Problemas do modelo tradicional (MVC / Web API)

1. Overhead estrutural
   • Muitos arquivos, classes e atributos para endpoints simples.
2. Baixa legibilidade para APIs pequenas
   • O fluxo da aplicação fica espalhado.
3. Inicialização mais lenta
   • Controllers, filters e reflection em excesso.
4. Verboso para APIs de baixo nível
   • Health checks, webhooks, callbacks, APIs internas.

O que o Minimal API melhora

• Reduz drasticamente boilerplate
• Melhora tempo de startup
• Simplifica manutenção de APIs pequenas e médias
• Facilita testes de conceito e microservices
• Permite injeção de dependência direta no endpoint

Para que tipo de aplicação é mais indicada

Indicada para

✅ Microservices

• Serviços pequenos, focados, com poucos endpoints

✅ APIs internas

• APIs consumidas apenas por outros serviços

✅ BFF (Backend for Frontend)

• APIs específicas para frontend/mobile

✅ Webhooks

• Endpoints simples e performáticos

✅ Serverless / Containers

• Startup rápido importa muito

Não é a melhor escolha para

❌ APIs gigantes e altamente complexas sem organização modular
❌ Times que dependem fortemente de:

• Filters complexos
• Convention-based routing pesado
• Controllers com herança e polimorfismo

⚠️ Importante: Minimal API não impede Clean Architecture. O erro comum é jogar regra de negócio no Program.cs.

Processo de criação via Command Line

Pré-requisitos

• .NET SDK 6+

Criar projeto Minimal API

dotnet new web -n MinimalApiSample
cd MinimalApiSample
dotnet run

Esse template já cria uma Minimal API.

Estrutura inicial típica:

MinimalApiSample
 ├─ Program.cs
 ├─ appsettings.json
 └─ Properties

Processo de criação via Visual Studio

1. File → New → Project
2. Escolha ASP.NET Core Empty
3. Avance
4. Dê um nome ao projeto:
   • Nesse caso utilizamos MinimalApiSample
   • Framework: .NET 6 ou superior
5. Create

O Visual Studio já gera um Program.cs no formato Minimal API.

Estrutura básica do Program.cs

using Microsoft.AspNetCore.Mvc;
using MinimalApiSample.Services;

var builder = WebApplication.CreateBuilder(args);

// REGISTRO DO SERVIÇO (DI)
builder.Services.AddScoped<IUserService, UserService>();

var app = builder.Build();

app.MapGet("/", () => "API Online");

app.Run();

Exemplo real: Método simples com injeção de dependência

Cenário

Buscar um usuário por ID.

Interface de domínio

using MinimalApiSample.Dtos;

namespace MinimalApiSample.Services
{
    public interface IUserService
    {
        UserDto GetById(Guid id);
    }
}

Implementação simples

using MinimalApiSample.Dtos;

namespace MinimalApiSample.Services
{
    public class UserService : IUserService
    {
        public UserDto GetById(Guid id)
        {
            return new UserDto(
                id,
                "Charlison"
            );
        }
    }
}

DTO

namespace MinimalApiSample.Dtos;

public record UserDto(
    Guid Id,
    string Name
);

Endpoint Minimal API

app.MapGet("/users/{id:guid}", (
    Guid id,
    [FromServices] IUserService userService
) =>
{
    var user = userService.GetById(id);

    if (user is null)
        return Results.NotFound();

    return Results.Ok(user);
});

Por que isso é importante tecnicamente

• Model binding automático
  • Guid id vem da rota
• DI direto no handler
  • Sem Controller, sem constructor
• Resultados explícitos
  • Results.Ok, Results.NotFound
• Performance
  • Menos reflection, menos pipeline

Boas práticas essenciais com Minimal API

✔️ Nunca colocar regra de negócio no endpoint
✔️ Usar classes/módulos para mapear rotas

Exemplo:

using MinimalApiSample.Services;

public static class UserEndpoints
{
    public static void Map(WebApplication app)
    {
        app.MapGet("/users/{id:guid}", GetById);
    }

    private static IResult GetById(
        Guid id,
        IUserService userService)
    {
        var user = userService.GetById(id);
        return user is null
            ? Results.NotFound()
            : Results.Ok(user);
    }
}

E no Program.cs:

UserEndpoints.Map(app);

Conclusão

Minimal APIs não substituem Controllers em todos os cenários, mas são uma excelente escolha quando o objetivo é:

• Reduzir boilerplate
• Melhorar tempo de startup
• Criar APIs mais diretas e performáticas
• Trabalhar com microservices, BFFs e APIs internas

Quando bem organizadas e alinhadas com uma arquitetura limpa, elas escalam tão bem quanto o modelo tradicional — com menos custo estrutural.

Código-fonte do projeto

Para facilitar o entendimento, disponibilizei o projeto completo com o exemplo de Minimal API, já organizado com separação de responsabilidades e boas práticas:

👉 Baixar o projeto no GitHub neste link:

Quer ver mais conteúdos como este?

Se você trabalha com .NET, C# e backend, este blog seguirá trazendo conteúdos práticos e objetivos sobre o ecossistema Microsoft, com foco em código, boas práticas e decisões técnicas aplicadas ao mundo real.

Acompanhe para continuar aprofundando seu domínio sobre a plataforma .NET.