Dominando as Convenções de Web API em ASP.NET Core para um Desenvolvimento Padronizado e Eficiente

O Poder das Convenções de Web API em ASP.NET Core

No universo do desenvolvimento de software, a padronização e a clareza são pilares fundamentais para a criação de aplicações robustas e de fácil manutenção. Quando se trata de Web APIs construídas com ASP.NET Core, as convenções de API desempenham um papel crucial nesse cenário. Elas oferecem um mecanismo para extrair e aplicar documentação comum de API a múltiplas ações, controladores ou até mesmo a todos os controladores dentro de um assembly. Este artigo explora em profundidade o conceito de convenções de Web API, seus benefícios e como implementá-las de forma eficaz, tomando como referência a discussão iniciada por Hassan Farooqui em seu artigo "Web API Conventions".

Entendendo as Convenções de Web API

As convenções de Web API no ASP.NET Core são, em essência, um substituto para a decoração individual de ações com o atributo [ProducesResponseType]. Em vez de anotar cada método de ação com os possíveis tipos de retorno e códigos de status HTTP, as convenções permitem definir esses padrões de forma centralizada. Isso resulta em um código mais limpo, menos verboso e mais fácil de gerenciar. A Microsoft disponibiliza um conjunto de convenções padrão através da classe Microsoft.AspNetCore.Mvc.DefaultApiConventions. Essas convenções cobrem os cenários mais comuns encontrados em operações CRUD (Create, Read, Update, Delete).

Por exemplo, uma ação GET que busca um recurso por ID, seguindo as convenções padrão, automaticamente terá documentado que pode retornar um código de status 200 (OK) com o recurso solicitado ou um 404 (Not Found) caso o recurso não exista. Da mesma forma, uma ação POST para criar um novo recurso pode ter documentado o retorno de um 201 (Created) em caso de sucesso ou um 400 (Bad Request) se a requisição for inválida. Essas convenções são reconhecidas em tempo de execução pelo Microsoft.AspNetCore.Mvc.ApiExplorer, que é a abstração do MVC para comunicação com geradores de documentação OpenAPI (anteriormente conhecido como Swagger).

Benefícios da Adoção de Convenções de Web API

A utilização de convenções de Web API traz uma série de vantagens significativas para o desenvolvimento:

• Padronização e Consistência: Garantem que as APIs sigam um padrão uniforme em relação aos tipos de retorno e códigos de status, tornando a API mais previsível e fácil de consumir.
• Redução de Código Repetitivo: Eliminam a necessidade de decorar cada ação individualmente com atributos [ProducesResponseType], diminuindo a verbosidade do código.
• Melhoria na Documentação da API: Facilitam a geração automática de documentação da API mais precisa e completa, pois as ferramentas de documentação como o Swagger conseguem interpretar essas convenções.
• Manutenção Simplificada: Alterações nos padrões de resposta podem ser feitas de forma centralizada, em vez de modificar inúmeras ações individualmente.
• Identificação de Desvios: Permitem identificar mais facilmente as ações que não seguem o padrão definido, auxiliando na manutenção da consistência.
• Integração com Analisadores de API: Os analisadores de API também reconhecem essas convenções, ajudando a identificar problemas e inconsistências durante o desenvolvimento.

Aplicando Convenções de Web API

Existem diferentes níveis nos quais as convenções de Web API podem ser aplicadas:

• Nível de Ação: Utilizando o atributo [ApiConventionMethod], é possível aplicar uma convenção específica a um método de ação individual.
• Nível de Controlador: O atributo [ApiConventionType] pode ser aplicado a um controlador, fazendo com que todas as ações dentro daquele controlador sigam a convenção especificada, a menos que uma convenção mais específica seja aplicada a uma ação individual.
• Nível de Assembly: Também é possível aplicar convenções a todos os controladores em um assembly, adicionando o atributo [ApiConventionType] no nível do assembly, geralmente no arquivo Startup.cs ou Program.cs (dependendo da versão do ASP.NET Core).

É importante notar que convenções mais específicas têm precedência sobre as menos específicas. Ou seja, uma convenção aplicada a uma ação sobrescreverá uma convenção aplicada ao controlador, que por sua vez sobrescreverá uma convenção aplicada no nível do assembly. No entanto, cada ação só pode estar associada a exatamente uma convenção; elas não se compõem.

Criando Convenções de Web API Personalizadas

Embora as DefaultApiConventions fornecidas pela Microsoft cubram muitos cenários comuns, pode haver situações em que seja necessário definir convenções personalizadas para atender a requisitos específicos de um projeto. Para criar convenções personalizadas, é preciso criar uma classe estática contendo métodos que representam os diferentes tipos de ações da API. Esses métodos devem ser anotados com atributos como [ProducesResponseType], [ProducesDefaultResponseType] e [ApiConventionNameMatch] para definir os tipos de retorno, códigos de status e como os métodos de convenção são mapeados para os nomes das ações.

Por exemplo, se uma aplicação frequentemente lida com operações de processamento em lote que podem resultar em um status 202 (Accepted), pode-se criar uma convenção personalizada para essas ações.

Exemplo Prático de Convenção Padrão

Considere um controlador de valores simples gerado por um template de projeto de API ASP.NET Core:

using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace WebApp1.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        // GET api/values
        [HttpGet]
        public ActionResult> Get()
        {
            return new string[] { "value1", "value2" };
        }

        // GET api/values/5
        [HttpGet("{id}")]
        public ActionResult Get(int id)
        {
            // Simulação de busca de um valor
            if (id == 0) return NotFound();
            return "value";
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody] string value)
        {
            // Lógica para criar um novo valor
        }

        // PUT api/values/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
            // Lógica para atualizar um valor existente
        }

        // DELETE api/values/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
            // Lógica para deletar um valor
        }
    }
}

Se as DefaultApiConventions forem aplicadas (o que geralmente acontece por padrão em projetos mais recentes com o atributo [ApiController]), a ação Get(int id), por exemplo, será automaticamente documentada como retornando 200 (OK) ou 404 (Not Found), mesmo sem os atributos [ProducesResponseType] explícitos. Os analisadores de API podem, inclusive, alertar sobre possíveis retornos não documentados se as convenções não estiverem cobrindo todos os cenários.

Analisadores de API e Convenções

Os analisadores de API (API Analyzers) são ferramentas valiosas que trabalham em conjunto com as convenções. Eles podem inspecionar o código e avisar os desenvolvedores quando as ações da API não estão em conformidade com as convenções aplicadas ou quando a documentação de resposta (como os atributos [ProducesResponseType]) está ausente ou incompleta. Isso ajuda a garantir que a documentação da API, especialmente a gerada pelo Swagger/OpenAPI, seja precisa e reflita o comportamento real da API.

Conclusão sobre Convenções de Web API

As convenções de Web API em ASP.NET Core são um recurso poderoso para promover a padronização, reduzir a verbosidade do código e melhorar a qualidade da documentação da API. Ao definir tipos de retorno e códigos de status comuns de forma centralizada, os desenvolvedores podem criar APIs mais consistentes, fáceis de entender e de manter. Seja utilizando as convenções padrão fornecidas pela Microsoft ou criando convenções personalizadas, a adoção dessa prática é um passo importante para a construção de Web APIs de alta qualidade. A integração com analisadores de API e ferramentas de documentação como o Swagger amplifica ainda mais os benefícios, resultando em um ciclo de desenvolvimento mais eficiente e colaborativo.