Olá, Devs! Vamos entender controle de versão no .Net?

Em um mundo dominado por sistemas interconectados e aplicações que constantemente comunicam entre si, a gestão e evolução das interfaces de programação de aplicações (APIs) é crucial, especialmente quando se refere à API do .Net. Em ambientes de desenvolvimento modernos, o controle de versão desempenha um papel essencial, garantindo que as modificações feitas na API não comprometam as aplicações existentes que a utilizam.

 

1. Importância do controle de versão

Os desenvolvedores geralmente evoluem uma API primeiramente porque querem introduzir novas funcionalidades ou por outro lado, melhorar sua performance. No entanto, se eles não gerenciarem as alterações corretamente, incompatibilidades podem surgir e consequentemente prejudicar sistemas em produção. Dessa forma, no contexto da API do .Net, precisamos de um mecanismo eficiente de controle de versão.

2. Métodos tradicionais e seus desafios

Tradicionalmente, desenvolvedores implementam o controle de versão em APIs através do versionamento por URL ou usando cabeçalhos HTTP. No primeiro método, eles especificam a versão diretamente na URL da API, como em: api/v1/recurso. No segundo, eles indicam a versão em um cabeçalho HTTP, como Accept-Version: v1.0.

Porém, desenvolvedores enfrentam desafios frequentemente. Quando eles incorporam a versão da API à URL, mudanças na estrutura da API podem resultar em URLs desorganizadas. Já o uso de cabeçalhos pode confundir desenvolvedores menos experientes.

3. Soluções que o .Net oferece

Na API do .Net, os desenvolvedores encontram mecanismos refinados para controlar as versões. O .Net introduziu uma biblioteca específica, a Microsoft.AspNetCore.Mvc.Versioning, para simplificar esse processo.

Ao usar essa biblioteca, os desenvolvedores podem especificar a versão da API através de um parâmetro de consulta, um cabeçalho personalizado ou diretamente no caminho da URL. Por exemplo, eles podem fazer uma solicitação assim: api/recurso?api-version=2.0.

Essa abordagem oferece vantagens notáveis. Primeiramente, ela estabelece um padrão uniforme, tornando o versionamento transparente e consistente. Além disso, com essa biblioteca, diferentes versões da API podem coexistir no mesmo endereço, facilitando uma transição suave entre elas.

4. Vamos ver um exemplo?

Considere o desenvolvimento de uma API que gerencia informações de estudantes. Na primeira versão, tem-se um método para obter o nome do estudante. Com o tempo, surge a necessidade de expandir essa funcionalidade, adicionando um método para obter a média de notas do estudante.

Sem o controle adequado de versão, essa nova funcionalidade poderia comprometer sistemas que dependem da versão anterior da API. No entanto, com o uso da biblioteca Microsoft.AspNetCore.Mvc.Versioning, é possível manter ambas as versões funcionando simultaneamente.

Como faço?

✓ Primeiramente, você terá que adicionar a biblioteca Microsoft.AspNetCore.Mvc.Versioning ao projeto. Isso pode ser feito via NuGet Package Manager ou via linha de comando:

✓ Depois de adicionada, configure o serviço:

Aqui, configuramos a API para ter uma versão padrão de 1.0. Se nenhuma versão for especificada na solicitação, ela assumirá 1.0 como padrão. A opção ReportApiVersions informará aos clientes quais versões estão disponíveis.

✓ Crie a Controller de estudantes

• Para versão 1 da API:

No exemplo acima, uma requisição GET para /api/students/1/name?api-version=1.0 retornará “Estudante 1: João Silva”.

• Para versão 2 da API:

Agora, uma requisição GET para /api/students/1/averageGrade?api-version=2.0 retornará “Estudante 1: Média 8.5”.

 

Posso fazer de outras formas?

Sim, você pode decorar a Controller com várias versões de API usando a anotação  [ApiVersion] várias vezes. Isso significa que a controller (ou a ação, dependendo de onde você coloca a anotação) pode atender a múltiplas versões da API.

Se você quiser que o método GetStudentName esteja disponível em ambas as versões “1.0” e “2.0”, você pode fazer o seguinte:

Neste exemplo, o método GetStudentName estará disponível para ambas api-version=1.0 e api-version=2.0 .

Se você quiser ser ainda mais granular e especificar versões em nível de ação (em vez da controller), você pode fazer isso também. Por exemplo, você pode ter um método na controller que é específico para uma versão e outro método para outra versão:

Neste cenário, o comportamento de GetStudentName pode variar dependendo da versão da API solicitada pelo cliente.

Existe também, a anotação [MapToApiVersion] que é usada para indicar explicitamente que uma ação específica em uma controller deve responder apenas a uma determinada versão da API, mesmo se o controlador em si estiver decorado para atender a várias versões.

Vamos ver como isso se aplica no contexto do nosso exemplo anterior:

Neste exemplo, a ação GetVersionSpecificInfo só responderá às solicitações que especificam api-version=2.0,  graças à anotação [MapToApiVersion(“2.0”)]. No  entanto, o método GetStudentName ainda está disponível para ambas as versões “1.0” e “2.0”, já que ele não possui uma anotação MapToApiVersion e a controller em si suporta ambas as versões.

A anotação [MapToApiVersion] fornece uma granularidade adicional, permitindo que os desenvolvedores definam comportamentos específicos para versões diferentes dentro da mesma controller.

5. Conclusão

O uso do versionamento, inicialmente, permite a coexistência dessas duas versões da API no mesmo endereço. Dessa forma, sistemas legados continuem a funcionar normalmente, enquanto novos sistemas ou sistemas atualizados podem optar por utilizar a versão mais recente da API.

Isso ilustra o poder e a flexibilidade do controle de versão na API do .NET, permitindo que os desenvolvedores evoluam suas APIs sem medo de quebrar sistemas existentes.

 

Legal né?!