Boas práticas no Desenvolvimento de APIs com ASP.NET Core – Parte #1

Neste artigo eu falo sobre algumas boas práticas no desenvolvimento de APIs com ASP.NET Core. Elas são fáceis de se aplicar em seu projeto, e o resultado é relevante não somente para sua equipe e projeto, mas para os sistemas que se integrarão a ele.

Sem querer ser chato, mas adianto: saber e não fazer é pior do que não saber. De nada adianta detectar alguns dos problemas discutidos mais adiante, e ficar passivo perante a eles. Seja proativo, e sinta-se confortável em refatorar. E se precisar alinhar refatorações com outras equipes, o faça se possível! Não use como desculpa para deixar como está. Assim você vai se destacar perante colegas de trabalho, chefe e o mercado em geral.

Vamos lá?


Padrão REST e Rotas

A equipe está confortável com seus próprios padrões de rotas de APIs até um membro novo entrar na equipe, ou necessitar integração a partir de um sistema externo.

Devido a falta de padronização ou desleixo/pressa é comum vermos endpoints que poderiam facilmente seguir o padrão REST utilizando de verbos. Por exemplo api/produto/cadastrar_novo.

Funciona? Sim! Mas pelo REST ser um padrão amplamente adotado, porque jogar contra e não a favor? Por convenção, se esperaria uma rota como api/produto, e método HTTP POST. Mais simples e melhor que quebrar a cabeça com nomes mais complicados, certo?

Claro que nem sempre a funcionalidade vai facilmente ser “traduzida” para o padrão REST de maneira simples. A ideia é apenas ter uma base firmada para não se quebrar tanto a cabeça ao definir rotas, e ao mesmo tempo facilitar a integração com outros sistemas e de novos membros da equipe.


Códigos de Status HTTP

É essencial entender os códigos de status HTTP, e retorná-los de acordo com o que está acontecendo em sua aplicação.

Já precisei integrar com um sistema que retornava código 200 (OK) para ERROS na requisição, e com conteúdo em string “Bad Request”. Pode parecer engraçado, mas esses sistemas existem por aí, e são um pesadelo para se integrar.

Com a padronização deles, o trabalho dos consumidores da API vai ser MUITO mais fácil.

Além disso, dependendo da requisição, existem mais de um tipo de erro que poderá ser retornado. Por exemplo, pode ser que o sistema esteja com erro interno, ou existe um erro no objeto da requisição, ou ainda que o identificador da rota não seja encontrado. Se for retornado um código 500, simplesmente a API que o consumir não vai saber o que precisa corrigir. Novamente, encontrei esse problema em mais de uma integração, e resultou em diversas chamadas no Teams e estresse para ambas as equipes.

Lista dos status mais comumente utilizados

  • 200 OK
  • 201 Created
  • 204 No Content
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

Legibilidade da classe Startup

A classe Startup tem um alto potencial para crescimento… o que não quer dizer que seja algo bom!

Com a adição de novas bibliotecas e suas configurações, além do gerenciamento de instâncias para injeção de dependências, ela cresce, e cresce RÁPIDO. Se uma ação não for tomada, vai resultar em código pouco legível e difícil de manter.

Mas o que fazer?

Uma solução é… utilizar métodos de extensão!

Assim, é possível delegar a responsabilidade dessas configurações para outras classes (estáticas) que estendem a interface IServiceCollection.

Por exemplo, considere o método ConfigureServices da classe Startup, abaixo.

Arrisco dizer que a chance de que você tenha encontrado algo assim em um projeto que tenha trabalhado é consideravelmente alta.

Uma solução é criar métodos de extensão para configuração dos repositórios e serviços, e transferir as chamadas existentes para eles.

Com isso, basta chamar a partir da classe Startup, no método ConfigureServices.

Mais legível, não acha? É possível aplicar esse mesmo processo para outras configurações que venham a surgir na classe Startup!


Inscreva-se na lista de espera do Método .NET Direto ao Ponto, um treinamento completo sobre C#, APIs com ASP.NET Core e Microsserviços:  Inscreva-se aqui.

São quase 200 vídeo-aulas sobre temas como C#, ASP NET Core 5, EF Core, CQRS, Clean Architecture, Autenticação e autorização com JWT, Testes Unitários, além de mini-cursos em Microsserviços, Performance em .NET, ASP NET Core e Azure, Docker, Carreira Internacional em .NET, e mais.


Conclusão

Foram apresentadas três boas práticas relativas ao desenvolvimento de APIs com ASP.NET Core. Existem muitas outras disponíveis, e pretendo ir abordando mais em artigos futuros.

Reforçando: é essencial estar disposto(a) a refatorar e melhorar a qualidade de código do projeto!

Bons estudos.