Versionar os endpoints de uma API REST tem se tornado um tipo de demanda cada vez mais frequente, sobretudo em cenários nos quais aplicações deste tipo são consumidas por diferentes sistemas. Uma simples alteração para atender a um projeto específico pode gerar a necessidade de manter múltiplos endpoints para uma mesma funcionalidade, garantindo assim sua compatibilidade com diferentes aplicações consumidoras.

E como podemos simplificar este processo de versionamento de APIs RESTem .NET, sobretudo se optarmos por implementações empregando Minimal APIs?

Já abordei em post anteriores neste blog o uso do projeto ASP.NET API Versioning, uma iniciativa mantida pela própria Microsoft e que traz excelentes resultados ao versionarmos endpoints em projetos baseados em Web API/Controllers. O artigo mais recente que publiquei sobre esta alternativa pode ser acessado a partir do seguinte link:

.NET 7 + ASP.NET Core: versionamento de APIs REST em um exemplo simples

E este suporte também está presente para o desenvolvimento com Minimal APIs. É o que abordarei neste artigo, com o exemplo aqui descrito já disponível no GitHub:

https://github.com/renatogroffe/ASPNETCore7-MinimalAPIs-Swagger-Versioning_ContagemAcessos

Caso achem útil a solução, peço por favor um ⭐️ no repositório do GitHub apoiando. Fica também o convite para que vocês me sigam lá!

Os detalhes desta aplicação foram demonstrados na prática em uma live recente no Canal .NET:

Será necessário adicionar ao arquivo .csproj da aplicação os packages:

• Asp.Versioning.Http: requerido para o mapeamento dos endpointsconfigurados via Minimal APIs;
• Asp.Versioning.Mvc.ApiExplorer: necessário para a capacidade de discovery dos endpoints existentes;
• Swashbuckle.AspNetCore: ferramentas para documentação com o Swagger/OpenAPI.

Os principais ajustes de configuração acontecerão em Program.cs:

• A chamada a AddApiVersioning irá configurar o uso da solução de versionamento de APIs, com a indicação da versão default a ser assumida (1.2) caso não se informe a mesma;
• Invocando AddApiExplorer definimos ainda que o versionamento estará presente na visualização HTML do Swagger/OpenAPI, assim como em sua possibilidade de uso nas rotas/URLs de acesso aos endpoints (além de query strings com o número da versão);
• Haverá ainda uma chamada a EnableApiVersionBinding para ativar o mecanismo de versionamento, além de invocações a AddTransient e AddSwaggerGen indicando a utilização das classes ConfigureSwaggerOptions e SwaggerDefaultValues (o código de ambas foi obtido a partir de um projeto de exemplo fornecido pela própria Microsoft – clique neste link para acessar);
• A variável apiContagem será uma instância do tipo IVersionedEndpointRouteBuilder (namespace Asp.Versioning.Builder), possibilitando que as diferentes rotas para endpoints sejam configuradas seguindo uma estrutura de versionamento. Isso acontecerá através do uso das extensões MapEndpointsContagemV1 e MapEndpointsContagemV2 que apontam para os endpoints implementados nesta aplicação de exemplo, com 2 chamadas a cada um desses métodos ativando o versionamento por URL e via query string;
• A chamada a UseSwaggerUI também contempla ajustes para tornar possível o versionamento dos endpoints nesta aplicação baseada em Minimal APIs (novamente tomei por base o exemplo disponibilizado pela Microsoft).

O retorno produzido pelos endpoints da versão 1.x está representado pela classe ResultadoContador, com a listagem a seguir trazendo a implementação para este tipo:

Os endpoints da versão 1.x serão configurados por meio do Extension Method MapEndpointsContagemV1:

• O uso de um MapGroup com a instância de IVersionedEndpointRouteBuilder permite aplicar o mesmo padrão de rotas para as diferentes versões indicadas;
• O método HasDeprecatedApiVersion indica que a versão 1.0 está como deprecated, com o seu uso devendo ser evitado. As versões 1.1 e 1.2 não contam com essa limitação, tendo sido configuradas por meio do método HasApiVersion;
• Nas 2 chamadas a MapGet o retorno produzido será uma instância do tipo ResultadoContador (namespace APIContagem.V1.Models), com o método MapToApiVersion indicando a quais versões cada implementação se refere.

Já na próxima listagem temos a definição de uma nova versão da classe ResultadoContador, correspondendo agora ao retorno produzido pelo endpoint da versão 2.0:

O Extension Method MapEndpointsContagemV2, por sua vez, permitirá que se configure o endpoint da versão 2.0. Desta vez foi utilizada a implementação da classe ResultadoContador que se encontra no namespace APIContagem.V2.Models, com ajustes similares àqueles empregados nos endpoints da versão 1.x:

Ao executar esta aplicação serão listadas como disponíveis as versões 1.0, 1.1, 1.2 e 2.0:

A versão 1.0 foi configurada como deprecated, com este aspecto sendo destacado na visualização HTML:

No teste a seguir temos um exemplo de utilização da versão 1.1:

Ao não especificar uma versão teremos o redirecionamento automático para a versão 1.2:

Já na próxima imagem temos um teste com o endpoint da versão 2.0:

E finalizo este post com um convite…

Acompanhe neste novo evento ONLINE e GRATUITO no Canal .NET dicas, truques e alternativas úteis para o desenvolvimento Back-End e de APIs REST com .NET 7, C#, ASP.NET Core e Azure Functions. Ao longo da apresentação será abordado o uso de diferentes frameworks, serviços na nuvem, mensageria e boas práticas de forma a facilitar e tornar mais dinâmica a implementação de soluções baseadas na plataforma .NET no seu dia a dia.

Teremos ainda novidades do .NET 8 e C# 12 demonstradas através de exemplos práticos!

Quando: 21/08/2023 (segunda) a partir das 21:00 — horário de Brasília

Faça sua inscrição em:
https://bit.ly/live-backend-dotnet-ago-2023