API Web em C# – Uma visão completa da estruturação de APIs com a abordagem de Derek Comartin

Analisando estruturas de API comuns

Derek começa fazendo a pergunta que a maioria dos desenvolvedores se faz ao criar um novo projeto de API Web no Visual Studio:

"Como você deve estruturar sua API HTTP?"

Ele reconhece imediatamente que os projetos de API Web podem ser organizados de diversas maneiras. Entre as estruturas de pastas mais comuns que Derek observa estão:

• Agrupamento por questões técnicas – colocando modelos em uma pasta "Modelos", controladores em uma pasta "Controladores" e serviços em "Serviços".

• Utilizando Arquitetura Limpa ou Arquitetura Cebola – onde os projetos são divididos em camadas (API, Aplicação, Domínio, Infraestrutura) para orientar as dependências.

• Combinando Domain-Driven Design (DDD) com arquitetura de fatias verticais – agrupando endpoints por funcionalidade, mas ainda mantendo objetos ricos em domínio.

Derek destaca que cada um desses padrões pode criar uma API RESTful que utiliza os métodos HTTP esperados (GET, POST, PUT, DELETE) para interagir com os recursos. Mas ele alerta para não se tirar conclusões precipitadas apenas com base na estrutura das pastas:

"Você pode ver entidades, agregados ou serviços de domínio, mas isso não significa que o código esteja realmente aplicando o design orientado a domínio — ele está apenas usando esses padrões."

Começando pela simplicidade, não pela complexidade.

Derek afirma que seu objetivo é simples:

"Um dos principais objetivos que eu queria alcançar com essa estrutura era a simplicidade."

Em vez de optar por uma arquitetura complexa no estilo do .NET Framework ou replicar padrões de livros didáticos, Derek escolhe as APIs mínimas do ASP.NET Core . Por quê? Porque facilitam a criação de APIs sem a sobrecarga de controladores e código repetitivo.

Ao criar um novo projeto de API Web no Visual Studio ou mesmo no Visual Studio Code, você pode começar com a caixa de diálogo Novo Projeto e selecionar API Web ASP.NET Core . Por padrão, você encontrará controladores, pastas e muitos elementos de estrutura básica. Derek argumenta que começar com algo menor — uma estrutura simples e limpa — costuma ser melhor.

A estrutura central da API Web de Derek

Derek apresenta a estrutura de sua aplicação web utilizando o .NET Core. Ele foi desenvolvido para oferecer suporte a serviços HTTP comuns e APIs RESTful que permitem a comunicação entre diferentes aplicativos de software.

Eis como ele organiza seu projeto de API web:

• Arquivo de endpoints – Um único arquivo para visualizar todas as rotas disponíveis na API. Em vez de vasculhar vários controladores, Derek quer uma visão geral rápida de todos os métodos GET, POST, PUT ou DELETE que a API suporta.

• Pasta Comum – Armazena código compartilhado, como filtros e extensões, usado em diferentes sistemas de software.

• Pastas de Recursos – Seguindo a filosofia de segmentação vertical, cada recurso novo ou existente recebe sua própria pasta. Por exemplo, uma pasta Posts pode incluir tudo o que é necessário para GET /posts/{id}, POST /posts, PUT /posts/{id} e DELETE /posts/{id}.

• Pasta de dados – Contém o modelo de dados e os mapeamentos de entidades. Nesse caso, o Entity Framework Core pode ser usado para uma integração perfeita com o banco de dados.

Ao agrupar os endpoints por funcionalidade, Derek evita espalhar a lógica por várias pastas não relacionadas.

Por que ele não impõe o Domain-Driven Design?

Derek já utilizou o Domain-Driven Design no passado, mas nesta estrutura de API Web em C# ele faz uma escolha fundamental:

"Não vamos usar o design orientado a domínio."

Em vez disso, ele "simplesmente deixa os dados serem dados". Seus modelos de dados são classes simples com propriedades básicas como:

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

public class Post  
{  
    public int Id { get; set; }  
    public string Title { get; set; }  
}

Nenhum comportamento desnecessário é incluído. Ao enviar uma solicitação POST para criar um novo recurso, a API simplesmente o salva. Ao enviar uma solicitação DELETE com um parâmetro de ID, o recurso correspondente é excluído.

Essa abordagem adota o estilo arquitetônico de Transferência de Estado Representacional (REST) ​​ao tratar os endpoints da API como verbos (método get, método post, método put, método delete) que atuam sobre recursos como Post, User ou Comment.

Analisando a solução no Visual Studio

Nesse momento, Derek abre sua solução do Visual Studio e nos apresenta o processo:

• O arquivo Endpoints lista todas as rotas — seja uma solicitação GET para buscar dados, uma solicitação POST para adicionar um novo recurso, uma solicitação PUT para atualizar dados ou um método DELETE para remover um recurso existente.

• A pasta Data contém mapeamentos para entidades como Post, User e Comment, conectadas a um banco de dados por meio do Entity Framework.

• A pasta Common contém lógica compartilhada para serviços HTTP, como filtros de validação e extensões.

• Cada pasta de funcionalidade (Posts, Comentários, Autenticação) contém todo o código necessário para esse recurso.

Este layout de pastas de projeto limpo evita a confusão de ter que vasculhar uma caixa de diálogo de projeto excessivamente complexa ou uma pasta de controladores espalhada.

Analisando um endpoint

Derek explica que cada endpoint em sua API Web ASP.NET Core é uma unidade de trabalho independente com três etapas claras:

1. Mapeamento – Define o método HTTP e a rota. Por exemplo, uma solicitação de exclusão pode mapear DELETE /posts/{id} para um método manipulador.

2. Contratos de Requisição e Resposta – Cada endpoint possui seu próprio corpo de requisição e tipo de resposta. Isso torna os serviços HTTP mais claros e evita a criação de camadas de DTOs duplicados.

3. Lógica – O método manipulador propriamente dito, onde a API busca dados no banco de dados, atualiza um modelo de dados ou retorna um código de status como return CreatedAtAction ou return NoContent.

Como Derek utiliza APIs mínimas, esses manipuladores são métodos estáticos. Com o ASP.NET Core, isso significa que você pode injetar dependências diretamente, sem a necessidade de uma classe de controlador complexa.

Por que APIs minimalistas parecem a escolha certa

Derek elogia as APIs minimalistas por sua simplicidade. Com o modelo minimalista do ASP.NET Core, você pode iniciar um projeto de API Web com apenas algumas linhas no arquivo Program.cs:

var app = WebApplication.CreateBuilder(args).Build();

var app = WebApplication.CreateBuilder(args).Build();

A partir daí, você adiciona seus métodos GET, métodos POST e solicitações PUT de forma direta.

Essa simplicidade ajuda a evitar o excesso de engenharia — algo que Derek vê com muita frequência quando os desenvolvedores copiam cegamente modelos de pacotes NuGet ou forçam novas classes de controlador para cada endpoint secundário.

Como a complexidade pode evoluir ao longo do tempo

Derek dá um exemplo concreto: a função "curtir uma publicação".

• No início, é simples: verifique se já existe uma curtida e, caso contrário, adicione uma.

• Mas, posteriormente, o aplicativo de software poderá precisar retornar instantaneamente a contagem de curtidas para páginas da web ou dispositivos móveis.

• Para aumentar a escalabilidade, você pode desnormalizar os dados adicionando uma propriedade LikeCount ao modelo de dados Post.

Isso abre novos desafios:

• Todos os métodos de inserção ou exclusão que afetam as curtidas devem atualizar a contagem corretamente.

• Se alguém adicionar um registro semelhante sem chamar a API, a contagem estará incorreta.

Derek demonstra que, à medida que a complexidade aumenta, você pode adicionar padrões como:

• Padrão de repositório para encapsular o acesso a dados.

• Agregue raízes para lidar com comportamentos (como incrementar LikeCount).

• Padrão de caixa de saída para garantir que eventos (como "PostLiked") sejam publicados.

Mas o ponto principal dele é claro:

"Não comece por aqui. Comece com o simples e evolua apenas se necessário."

Finalizando com o Takeaway do Derek

Derek conclui retomando sua principal lição para desenvolvedores de API Web em C#:

"Comece pelo simples."

Ao usar o ASP.NET Core Web API ou o ASP.NET Web API no Visual Studio, é fácil exagerar na complexidade desde o primeiro dia — adicionando todas as pastas, padrões e pacotes NuGet que você já viu.

Mas Derek adverte: não aplique soluções cegamente. Compreenda os métodos HTTP de que você precisa, os dados com os quais está trabalhando e os sistemas de software entre os quais você está permitindo a comunicação. Crie suas APIs RESTful passo a passo.

Para quem usa o Visual Studio Code ou qualquer outro ambiente de desenvolvimento integrado, o conselho dele continua válido: seja um projeto novo ou um recurso existente, mantenha a estrutura do projeto o mais simples possível e adicione padrões somente quando a complexidade do mundo real exigir.

Conclusão

O vídeo de Derek Comartin é mais do que apenas um guia para construir uma API Web em C# — é um lembrete de que uma boa arquitetura começa com clareza, não com confusão. Ao percorrer sua configuração real de API Web ASP.NET Core no Visual Studio, ele demonstra como APIs minimalistas, pastas de recursos e modelos de dados simples podem formar a base para APIs RESTful que permitem uma comunicação perfeita entre diferentes aplicativos de software sem complicar demais o design.

Se você quiser ver essa abordagem em ação e ouvir a perspectiva de Derek em primeira mão, o vídeo dele é um excelente recurso. Seu canal está repleto de discussões igualmente esclarecedoras sobre sistemas de software, serviços web e desenvolvimento ASP.NET Core — uma fonte indispensável para qualquer desenvolvedor que queira aprimorar suas habilidades e manter seus projetos organizados, práticos e preparados para o futuro.