ASP.NET Core APIs - 10 dicas de design

 Neste artigo vou apresentar 10 dicas de design para APIs ASP.NET Core de forma que suas APIs siga os padrões mais recomendados.
 
Para ter uma API robusta e fácil de manter e estender é necessãrio seguir padrões de design de forma que seu código esteja aderente com as boas práticas.

Para isso vejamos a seguir dez dicas para alcançar este objetivo.

1- Definir um contrato de API consistente

Um contrato claro define como os clientes devem interagir com a API. Use atributos, como [HttpGet] e [HttpPost], para definir rotas e métodos HTTP.

[ApiController]
[Route("api/produtos")]
public class ProdutosController : ControllerBase
{
    [HttpGet]
    public IActionResult ObterProdutos()
    {
        // Lógica para obter produtos
        return Ok(produtos);
    }

    [HttpPost]
    public IActionResult CriarProduto([FromBody] Produto novoProduto)
    {
        // Lógica para criar um novo produto
        return CreatedAtAction(nameof(ObterProdutos), 
                    new { id = novoProduto.Id }, novoProduto);
    }
}

Para criar especificações bem definidas podemos usar ferramenas como o Swagger para garantir a consistência e transparência no contrato da API.

2- Realizar o tratamento do versionamento

O versionamento de API consiste em atribuir uma versão a cada mudança significativa na API, seja ela uma alteração no endpoint, nos parâmetros, nos dados retornados ou em qualquer outro aspecto da API. Isso permite que os desenvolvedores que consomem a API saibam qual versão da API eles estão usando e se precisam realizar alguma atualização para continuar usando a API de forma correta.

Utilize versionamento para garantir a compatibilidade entre versões antigas e novas da API.

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/produtos")]
public class ProdutosController : ControllerBase
{
    // Implementação da versão 1.0 da API
}

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/produtos")]
public class ProdutosV2Controller : ControllerBase
{
    // Implementação da versão 2.0 da API
}

3- Limite de taxa e estrangulamento

Evite sobrecargas implementando limites de taxa (Rate Limit) para prevenir abusos.

O limite de taxa é uma técnica que limita o número de solicitações que podem ser feitas à API em um determinado período de tempo. Isso pode ser feito usando o middleware RequestRateLimiterMiddleware, que está disponível no pacote NuGet Microsoft.AspNetCore.RateLimiting.

Para usar o RequestRateLimiterMiddleware, primeiro você precisa criar uma instância da classe RequestRateLimiter. Esta classe define o número máximo de solicitações que podem ser feitas por segundo e o período de tempo em que as solicitações são contadas.

/ Configuração no Startup.cs
builder.Services.AddMvc(options =>
{
    options.Filters.Add(new RateLimitAttribute());
});

[ApiController]
[Route("api/produtos")]
[RateLimitRequests(PerMinute = 100)]
public class ProdutosController : ControllerBase
{
    // Implementação da API com limites de taxa
}

O estrangulamento é uma técnica que retarda as solicitações quando a API está sobrecarregada. Isso pode ser feito usando o middleware RequestQueueMiddleware, que está disponível no pacote NuGet Microsoft.AspNetCore.RequestQueue.

Para usar o RequestQueueMiddleware, primeiro você precisa criar uma instância da classe RequestQueueOptions. Esta classe define o tamanho da fila de solicitações e o tempo limite para as solicitações na fila.

4- Autenticação e Autorização

Proteja sua API com autenticação e autorização.

[ApiController]
[Route("api/produtos")]
[Authorize]
public class ProdutosController : ControllerBase
{
    // Implementação da API protegida
}

ASP.NET Core fornece vários mecanismos de autenticação, incluindo:

5- Paginação e filtro

Permita aos clientes controlar a quantidade de dados retornados.

[HttpGet]
[Route("api/produtos")]
public IActionResult ObterProdutos([FromQuery] int pagina = 1, 
                                    [FromQuery] int tamanhoPagina = 10)
{
    // Lógica de paginação
    var produtosPaginados = produtos.Skip((pagina - 1) 
                        * tamanhoPagina).Take(tamanhoPagina);

    return Ok(produtosPaginados);
}

A paginação pode ajudar a melhorar o desempenho de uma API ASP.NET Core ao retornar apenas uma parte dos dados do banco de dados em cada solicitação. Isso pode ser útil para APIs que trabalham com grandes quantidades de dados.

O filtro pode ajudar a melhorar a usabilidade de uma API ASP.NET Core ao permitir que os usuários gerenciem os dados retornados pela API. Isso pode ser útil para APIs que fornecem acesso a dados complexos ou que são usadas por usuários com necessidades específicas.

6- Tratamento de grandes respostas

Ofereça opções aos clientes para requisitar respostas parciais para gerenciar grandes quantidades de dados de forma eficiente. Para isso você pode implementar a paginação e permitir que os clientes solicitem partes específicas dos dados.

Exemplo:

[ApiController]
[Route("api/produtos")]
public class ProdutosController : ControllerBase
{
   // Suponha que você tenha uma lista de produtos
    private readonly List<Produto> produtos; 

    public ProdutosController()
    {
        // Inicialização da lista de produtos (exemplo)
        produtos = new List<Produto>
        {
            new Produto { Id = 1, Nome = "Produto1" },
            // ...
        };
    }

    [HttpGet]
    public IActionResult ObterProdutos([FromQuery] int pagina = 1, 
                                         [FromQuery] int tamanhoPagina = 10)
    {
        var produtosPaginados = produtos.Skip((pagina - 1) * 
                                            tamanhoPagina).Take(tamanhoPagina);

        var resultado = new
        {
            PaginaAtual = pagina,
            TamanhoPagina = tamanhoPagina,
            TotalItens = produtos.Count,
            Itens = produtosPaginados
        };

        return Ok(resultado);
    }
}

 

7- Testes e Mock

Escreva testes unitários e de integração para garantir a robustez da API. Desenvolva suites de testes e forneça endpoints mocks para realizar o teste de integração.

O mocking é uma técnica de teste que permite substituir dependências da sua API por objetos simulados. Isso pode ser útil para testar cenários em que as dependências da sua API podem não estar disponíveis ou quando você deseja controlar o comportamento das dependências.

Aqui estão alguns exemplos de como os testes e o mocking podem ser usados em uma API ASP.NET Core:

8 - Segurança e dados privados

Use HTTPS, evite informações sensíveis nos logs e proteja dados privados.

Siga as boas práticas incluindo encriptação de dados e validação de input e crie logs de auditoria.

  • Criptografia: Você pode usar a criptografia de dados em repouso ou em trânsito para proteger os dados confidenciais.
  • Medidas de segurança de rede: Você pode usar um firewall para bloquear o acesso não autorizado à sua API e uma VPN para permitir que os usuários se conectem à sua API com segurança.
  • Manutenção de software atualizado: Você pode usar o NuGet para instalar patches de segurança para o ASP.NET Core e outros componentes de sua API.

    • 9-  Documentação

    Utilize ferramentas como o Swagger UI para gerar documentação automaticamente.

    Em uma API ASP.NET Core, a documentação pode ser gerada de várias maneiras. Uma maneira é gerar a documentação automaticamente usando o Swagger ou o OpenAPI. Essas ferramentas geram uma documentação interativa que pode ser usada para testar a API e visualizar as informações sobre os endpoints, parâmetros e respostas.

    Outra maneira de gerar a documentação é escrever a documentação manualmente. Isso pode ser feito usando um editor de texto ou uma ferramenta de documentação. A documentação manual pode ser mais detalhada e específica do que a documentação gerada automaticamente.

    Aqui estão algumas dicas para gerar a documentação de uma API ASP.NET Core:

    Aqui estão algumas ferramentas que podem ser usadas para gerar a documentação de uma API ASP.NET Core:

    10 - Tratamento de erros

    Forneça mensagens de erro claras e utilize códigos HTTP apropriados.

    [ApiController]
[Route("api/produtos")]
public class ProdutosController : ControllerBase
{
    // Suponha que você tenha uma lista de produtos
    private readonly List<Produto> produtos; 
        public ProdutosController()
    {
        // Inicialização da lista de produtos (exemplo)
        produtos = new List<Produto>
        {
            new Produto { Id = 1, Nome = "Produto1" },
            // ...
        };
    }
        [HttpGet("{id}")]
    public IActionResult ObterProdutoPorId(int id)
    {
        var produto = produtos.FirstOrDefault(p => p.Id == id);
            if (produto == null)
        {
            // Retorna um código HTTP 404 Not Found com 
            //    uma mensagem de erro
            return NotFound($"Produto com ID {id} não encontrado.");
        }
            return Ok(produto);
    }
      [HttpPost]
  public IActionResult CriarProduto([FromBody] Produto novoProduto)
  {
      if (novoProduto == null)
      {
          // Retorna um código HTTP 400 Bad Request 
          //  com uma mensagem de erro
          return BadRequest("Dados do produto inválidos.");
      }
            // Lógica para criar um novo produto
          // Retorna um código HTTP 201 Created com o produto criado
       return CreatedAtAction(nameof(ObterProdutoPorId), 
                                  new { id = novoProduto.Id }, novoProduto);
    }
}

    Em uma API ASP.NET Core, o tratamento de erros pode ser feito usando o middleware ExceptionHandler. Este middleware intercepta todas as exceções que ocorrem na API e as converte em respostas HTTP.

    Aqui estão algumas dicas para tratar erros em uma API ASP.NET Core:

    Aqui estão alguns exemplos de como o tratamento de erros pode ser usado em uma API ASP.NET Core:

    Seguindo essas dicas sua API e seus clientes agradem !!!

    E estamos conversados...

    "Pois, assim como o Pai ressuscita os mortos, e os vivifica, assim também o Filho vivifica aqueles que quer."
    João 5:21

    Referências:

    José Carlos Macoratti