Nesse artigo vamos ver de forma objetiva como criar versionamento de APIs na plataforma .NET.
Configuração e abordagens
Vamos utilizar o pacote Microsoft.AspNetCore.Mvc.Versioning instalado em nossa aplicação.
Abaixo a configuração do arquivo de Startup.cs com as 3 abordagens mais utilizadas: Url Path, Header e Query String. Nesse artigo iremos abordar o Url Path ( via namespace).
Primeiro passo é adicionar o suporte usando o método AddApiVersioning (1) e configurar algumas opções:
- UseApiBeahavior: essa opção irá aplicar o versionamento para todas as APIs que conterem o atributo ApiControllerAttribute. Quando falso, todas as rotas serão versionadas sem distinção. Caso contrário, as rotas que contém o atributo serão consideradas como APIs versionadas.
- ReportApiVersions: toda chamada deverá incluir dois valores de header no retorno: api-supported-versions e api-deprecated-versions, descrevendo versões suportadas e depreciadas.
- AssumeDefaultVersionWhenUnspecified: quando marcada ao consumir a API sem a informação de versão, a configuração DefaultApiVersion será usada para definir qual é a versão padrão.
- DefaultApiVersion: valor padrão para o número da versão (valor padrão é 1.0).
- ApiVersionReader: essa opção fará a escolha de qual será a estratégia (url path, query string ou header value) utilizada pela aplicação para recuperar a versão.
Resumindo…
- VIA QUERYSTRING: api.com/endpoint?version=3.0
- VIA URL PATH: api/com/v1 (analisada aqui no artigo)
- VIA HEADER: “Accept”=“application/vnd.api.v1.json”
- VIA SUBDOMÍNIO: v1.api.com
URL PATH
Utilizando o formato “{version:apiVersion}” (2) ao descrever a rota como iremos informar onde o número de versão será incluído.
O atributo ApiVersion é utilizado para aplicar uma versão específica a uma ação, isso possibilita que múltiplas versões possam ser associadas em um mesmo controlador.
Depreciação de versão
Usando o mesmo atributo ApiVersion (3) podemos depreciar uma versão.
Configurando o swagger para exibição de versões
Para cada versão da API foi criada uma pasta (V1, V2 e V3), com os Controllers em seus respectivos namespaces.
Agora precisamos configuração o swagger para exibir a documentação para cada versão da nossa API. Para adicionar esse suporte, dois pacotes devem ser adicionados: Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer e Swashbuckle.AspNetCore.
Vamos voltar ao arquivo de Startup.cs e alterá-lo: A primeira configuração adicionada é referente ao ApiExplorer usando o método AddVersionedApiExplorer (4) com as configurações:
- GroupNameFormat: definição do formato para o número da versão (padrão “vmajor[.minor][-status]”).
- SubstituteApiVersionInUrl: esta opção fará o ApiExplorer substituir os parâmetros da versão de sua API pelos modelos de rota encontrados (“api/v{version:apiVersion}/usuario”), onde a substituição pela versão será feita automaticamente.
O segundo trecho de código onde é feita a chamada do AddSwaggerGen e ConfigureOptions (5), adiciona o suporte do Swagger.
Para separar essas múltiplas versões dentro de sua aplicação você pode separar através de namespaces (6):
Acredito que o versionamento por Url Path é o mais intuitivo dentro dos 3 mais conhecidos (Url Path, Header e Query String) e por isso foi motivo de estudo nesse artigo.