Endpoints

Endpoints no Repository Pattern: Implementando um CRUD Completo

Configurando os Endpoints com Minimal APIs

Os endpoints HTTP são configurados para expor as operações CRUD do repositório através da infraestrutura do ASP.NET Core. No arquivo Program.cs, os endpoints básicos são substituídos por implementações completas que consomem a abstração IProductRepository, garantindo a separação entre a camada de apresentação e a lógica de acesso a dados.

Endpoint GET para Listagem com Paginação

O endpoint inicial de listagem é refatorado para incluir suporte a paginação e tratamento adequado de cancelamento assíncrono:

// Endpoint inicial simplificado
app.MapGet("/v1/products", async (IProductRepository repository) 
    => await repository.GetAllAsync());

Substituído por:

// Endpoint completo com paginação e tratamento de token
app.MapGet(
    "/v1/products", 
    async (
        CancellationToken token, 
        IProductRepository repository, 
        int skip = 0, 
        int take = 25)
    => Results.Ok(await repository.GetAllAsync(skip, take, token)));

Características implementadas:

Paginação nativa: Parâmetros skip e take com valores padrão permitem consultas como /v1/products?skip=10&take=5
Controle assíncrono: O CancellationToken é injetado automaticamente pelo framework para permitir o cancelamento de operações longas
Resposta HTTP semântica: Uso de Results.Ok() retorna código de status 200 com o corpo da resposta formatado como JSON
Desacoplamento: A dependência é na interface IProductRepository, não na implementação concreta

Endpoint GET por ID

O endpoint para recuperação de um recurso específico é implementado com rota parametrizada:

// Substituição do endpoint placeholder
app.MapGet("/v1/products", (AppDbContext context) => "Hello World!");

Por:

// Endpoint com parâmetro de rota
app.MapGet(
    "/v1/products/{id}", 
    async (
        CancellationToken token,
        IProductRepository repository, 
        int id)
    => Results.Ok(await repository.GetByIdAsync(id, token)));

Observações técnicas:

O {id} na rota é um route parameter que captura o valor da URL
O sistema de model binding do ASP.NET Core converte automaticamente o valor para int
A ausência do produto resulta em resposta null, que pode ser tratada com Results.NotFound() em implementações mais robustas

Endpoint POST para Criação

A criação de novos recursos utiliza o verbo HTTP POST com dados no corpo da requisição:

app.MapPost("/v1/products", (AppDbContext context) => "Hello World!");

Por:

app.MapPost(
    "/v1/products", 
    async (
        CancellationToken token, 
        IProductRepository repository, 
        Product product)
    => Results.Ok(await repository.CreateAsync(product, token)));

Processo de deserialização:

O framework lê o corpo da requisição como JSON
Converte os dados para uma instância da classe Product
Injeta automaticamente os parâmetros token, repository e product
Executa a operação de criação através do repositório

Endpoint PUT para Atualização

A atualização de recursos existentes utiliza o verbo HTTP PUT:

app.MapPut("/v1/products", (AppDbContext context) => "Hello World!");

Substituído por:

app.MapPut(
    "/v1/products", 
    async (
        CancellationToken token, 
        IProductRepository repository, 
        Product product)
    => Results.Ok(await repository.UpdateAsync(product, token)));

Considerações de design:

O objeto Product completo é enviado no corpo da requisição, incluindo o Id
O repositório é responsável por localizar e atualizar a entidade correspondente
Em APIs RESTful puristas, considera-se usar PATCH para atualizações parciais

Endpoint DELETE para Exclusão

A exclusão de recursos utiliza o verbo HTTP DELETE com identificação através da rota:

app.MapDelete("/v1/products", (AppDbContext context) => "Hello World!");

Substituído por:

app.MapDelete(
    "/v1/products/{id}", 
    async (
        CancellationToken token, 
        IProductRepository repository, 
        int id) =>
    {
        var product = await repository.GetByIdAsync(id, token);
        return product == null 
            ? Results.NotFound() 
            : Results.Ok(await repository.DeleteAsync(product, token));
    });

Análise da implementação:

Verificação de existência: Primeiro busca o produto para confirmar sua existência
Resposta condicional: Retorna 404 Not Found se o recurso não existir
Operação de exclusão: Executa a exclusão apenas após confirmação
Retorno do objeto excluído: Convenção que permite ao cliente confirmar o que foi removido

Padrões e Estruturas Comuns

Injeção Automática de Parâmetros

O sistema de Minimal APIs do ASP.NET Core fornece dependency injection automática para:

Serviços registrados: Como IProductRepository configurado com AddTransient<>()
Parâmetros de requisição: Como CancellationToken para controle assíncrono
Dados de rota e query: Como id, skip, e take

Tratamento Semântico de Respostas

Os helpers Results.* proporcionam respostas HTTP padronizadas:

Método Helper

Código HTTP

Uso Típico

Results.Ok()

200 OK

Operação bem-sucedida com corpo

Results.NotFound()

404 Not Found

Recurso não encontrado

Results.Created()

201 Created

Recurso criado com URL de localização

Results.NoContent()

204 No Content

Operação bem-sucedida sem corpo

Executando e Testando a Aplicação

Inicialização do Serviço

Ao executar a aplicação, o sistema registra as informações de inicialização:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5039
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Dev\RepositoryStore

A aplicação fica disponível na porta 5039, configurada automaticamente pelo Kestrel, o servidor web embutido do ASP.NET Core.

Configuração do Ambiente de Banco de Dados

Para operações de persistência real, o SQL Server em container Docker precisa ser inicializado:

# Listar containers Docker
docker container ls -a

# Iniciar o container do SQL Server
docker container start 9dc633ab7148

Saída esperada:

9dc633ab7148

Esta etapa é necessária apenas para ambientes de desenvolvimento utilizando containers. Em produção, a conexão seria configurada para um servidor de banco de dados gerenciado.

Sequência de Testes no Postman

A validação dos endpoints é realizada através de requisições HTTP sequenciais, simulando o fluxo completo de operações CRUD.

1. Criação de Produto (POST)

Requisição:

POST http://localhost:5039/v1/products

{
    "title": "Product 01"
}

Resposta (200 OK):

{
    "id": 1,
    "title": "Product 01"
}

Análise: A operação de criação retorna o objeto persistido, incluindo o identificador gerado pelo banco de dados. Em APIs RESTful puristas, considera-se retornar 201 Created com cabeçalho Location apontando para o recurso criado.

2. Listagem de Produtos (GET)

Requisição:

GET http://localhost:5039/v1/products

Resposta (200 OK):

[
    {
        "id": 1,
        "title": "Product 01"
    }
]

Observação: A listagem retorna um array JSON, mesmo contendo um único elemento, mantendo consistência com o contrato da API.

3. Obtenção por ID (GET com parâmetro)

Requisição:

GET http://localhost:5039/v1/products/1

Resposta (200 OK):

{
    "id": 1,
    "title": "Product 01"
}

Padrão RESTful: A URL /v1/products/{id} segue a convenção de recursos aninhados, onde cada produto é acessível através de seu identificador único.

4. Atualização de Produto (PUT)

Requisição:

PUT http://localhost:5039/v1/products

{
    "id": 1,
    "title": "Product 01 - Atualizado"
}

Resposta (200 OK):

{
    "id": 1,
    "title": "Product 01 - Atualizado"
}

Idempotência: O verbo PUT é idempotente - múltiplas requisições idênticas produzem o mesmo resultado que uma única requisição.

5. Verificação da Atualização

Requisição:

GET http://localhost:5039/v1/products

Resposta (200 OK):

[
    {
        "id": 1,
        "title": "Product 01 - Atualizado"
    }
]

Consistência de dados: A verificação confirma que a atualização foi persistida corretamente no banco de dados.

6. Exclusão de Produto (DELETE)

Requisição:

DELETE http://localhost:5039/v1/products/1

Resposta (200 OK):

{
    "id": 1,
    "title": "Product 01 - Atualizado"
}

Convenção de retorno: A API retorna o objeto excluído, permitindo ao cliente confirmar a operação. Alternativamente, poderia retornar 204 No Content sem corpo.

7. Verificação após Exclusão

Requisição:

GET http://localhost:5039/v1/products

Resposta (200 OK):

[]

Estado final: A listagem vazia confirma que o recurso foi removido permanentemente do repositório.

Melhorias e Boas Práticas

Validação de Entrada

Para aumentar a robustez da API, a validação dos dados de entrada pode ser implementada:

// Endpoint POST com validação
app.MapPost("/v1/products", async (
    CancellationToken token,
    IProductRepository repository,
    IValidator<Product> validator,
    Product product) =>
{
    var validationResult = await validator.ValidateAsync(product, token);
    if (!validationResult.IsValid)
    {
        return Results.ValidationProblem(validationResult.ToDictionary());
    }
    
    var createdProduct = await repository.CreateAsync(product, token);
    return Results.Created($"/v1/products/{createdProduct.Id}", createdProduct);
});

Versionamento de API

Considerar implementar versionamento para evolução da API:

app.MapGet("/v2/products", async (
    CancellationToken token,
    IProductRepository repository,
    int page = 1,
    int pageSize = 20) =>
{
    var skip = (page - 1) * pageSize;
    var products = await repository.GetAllAsync(skip, pageSize, token);
    
    var response = new
    {
        Page = page,
        PageSize = pageSize,
        TotalCount = await repository.GetCountAsync(token),
        Items = products
    };
    
    return Results.Ok(response);
});

Tratamento de Exceções

Implementar um middleware para tratamento uniforme de erros:

app.UseExceptionHandler(exceptionHandlerApp =>
{
    exceptionHandlerApp.Run(async context =>
    {
        context.Response.StatusCode = StatusCodes.Status500InternalServerError;
        context.Response.ContentType = "application/json";
        
        var exception = context.Features.Get<IExceptionHandlerFeature>()?.Error;
        
        var response = new
        {
            Title = "An error occurred",
            Status = context.Response.StatusCode,
            Detail = exception?.Message,
            TraceId = context.TraceIdentifier
        };
        
        await context.Response.WriteAsJsonAsync(response);
    });
});

Documentação com OpenAPI

A integração com Swagger/OpenAPI facilita a documentação e teste da API:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// No pipeline de requisições
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Conclusões e Próximas Etapas

Resultados Alcançados

A implementação demonstra a integração bem-sucedida entre:

Minimal APIs para definição concisa de endpoints
Repository Pattern para abstração do acesso a dados
Dependency Injection para inversão de controle
Entity Framework Core para persistência ORM
Testes manuais com Postman para validação funcional

Princípios Arquiteturais Aplicados

Separation of Concerns: Endpoints lidam com HTTP, repositórios com dados
Dependency Inversion: Dependências de abstrações, não de implementações
Single Responsibility: Cada componente tem uma responsabilidade bem definida
Open/Closed: Extensível através de novas implementações de IProductRepository

Recomendações para Evolução

Autenticação e Autorização: Implementar mecanismos como JWT para segurança
Logging Estruturado: Adicionar logs semânticos para monitoramento
Testes Automatizados: Desenvolver testes de integração e unitários
Cache Estratégico: Implementar cache para endpoints de leitura frequente
Versionamento de API: Estruturar para evolução sem breaking changes
Documentação Automática: Expandir documentação com exemplos e códigos de erro

A arquitetura resultante proporciona uma base sólida para desenvolvimento de APIs escaláveis e manteníveis, onde modificações na camada de persistência ou na lógica de negócio podem ser realizadas com impacto mínimo nos consumidores da API.

AnteriorInterfaces PróximoRepositórios Genéricos

Atualizado há 2 meses

hashtagConfigurando os Endpoints com Minimal APIs

hashtagEndpoint GET para Listagem com Paginação

hashtagCaracterísticas implementadas:

hashtagEndpoint GET por ID

hashtagObservações técnicas:

hashtagEndpoint POST para Criação

hashtagProcesso de deserialização:

hashtagEndpoint PUT para Atualização

hashtagConsiderações de design:

hashtagEndpoint DELETE para Exclusão

hashtagAnálise da implementação:

hashtagPadrões e Estruturas Comuns

hashtagInjeção Automática de Parâmetros

hashtagTratamento Semântico de Respostas

hashtagExecutando e Testando a Aplicação

hashtagInicialização do Serviço

hashtagConfiguração do Ambiente de Banco de Dados

hashtagSequência de Testes no Postman

hashtag1. Criação de Produto (POST)

hashtag2. Listagem de Produtos (GET)

hashtag3. Obtenção por ID (GET com parâmetro)

hashtag4. Atualização de Produto (PUT)

hashtag5. Verificação da Atualização

hashtag6. Exclusão de Produto (DELETE)

hashtag7. Verificação após Exclusão

hashtagMelhorias e Boas Práticas

hashtagConclusões e Próximas Etapas

hashtagResultados Alcançados

hashtagPrincípios Arquiteturais Aplicados

hashtagRecomendações para Evolução

Configurando os Endpoints com Minimal APIs

Endpoint GET para Listagem com Paginação

Características implementadas:

Endpoint GET por ID

Observações técnicas:

Endpoint POST para Criação

Processo de deserialização:

Endpoint PUT para Atualização

Considerações de design:

Endpoint DELETE para Exclusão

Análise da implementação:

Padrões e Estruturas Comuns

Injeção Automática de Parâmetros

Tratamento Semântico de Respostas

Executando e Testando a Aplicação

Inicialização do Serviço

Configuração do Ambiente de Banco de Dados

Sequência de Testes no Postman

1. Criação de Produto (POST)

2. Listagem de Produtos (GET)

3. Obtenção por ID (GET com parâmetro)

4. Atualização de Produto (PUT)

5. Verificação da Atualização

6. Exclusão de Produto (DELETE)

7. Verificação após Exclusão

Melhorias e Boas Práticas

Conclusões e Próximas Etapas

Resultados Alcançados

Princípios Arquiteturais Aplicados

Recomendações para Evolução