Estratégias de versionamento

Resumo

APIs evoluem sem quebrar clientes existentes. O pacote Asp.Versioning habilita versionamento por URL, query string, header ou media type, além de depreciação e convenções.

1. Objetivos de Aprendizagem#

• Instalar e configurar o versionamento de API.
• Aplicar as estratégias: URL, query string e header.
• Depreciar versões e usar convenções.

2. Pré-requisitos#

• Controllers e roteamento (Módulo 18).

3. Conceito#

Versionamento permite manter v1 estável enquanto v2 introduz mudanças incompatíveis. O porquê: contratos públicos não podem quebrar clientes já integrados. Estratégias comuns:

• URL: /api/v1/produtos (explícito, cacheável).
• Query string: /api/produtos?api-version=1.0.
• Header: Api-Version: 1.0.
• Media type: Accept: application/json;v=1.0.

4. Mão na Massa#

4.1. Setup#

dotnet add Catalog.Api package Asp.Versioning.Mvc
dotnet add Catalog.Api package Asp.Versioning.Mvc.ApiExplorer

4.2. Implementação Passo a Passo#

1. Configuração:

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true; // adiciona headers api-supported-versions
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new QueryStringApiVersionReader("api-version"),
        new HeaderApiVersionReader("Api-Version"));
})
.AddMvc();

2. Controllers versionados:

[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/produtos")]
[ApiController]
public class ProdutosV1Controller : ControllerBase { /* ... */ }

[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/produtos")]
[ApiController]
public class ProdutosV2Controller : ControllerBase { /* ... */ }

3. Depreciar uma versão:

[ApiVersion(1.0, Deprecated = true)]

4.3. Executando#

curl http://localhost:5000/api/v1/produtos
curl "http://localhost:5000/api/produtos?api-version=2.0"
curl -H "Api-Version: 2.0" http://localhost:5000/api/produtos

5. Exemplo Completo#

Com ReportApiVersions = true, as respostas trazem api-supported-versions e api-deprecated-versions, informando clientes sobre o ciclo de vida.

6. Boas Práticas e Armadilhas#

Atenção

versionar cedo demais gera manutenção duplicada. Mudanças retrocompatíveis (novo campo opcional) não exigem nova versão.

7. Segurança e Produção#

• Comunique claramente a política de depreciação e a data de fim de suporte de cada versão.

8. Exercícios#

• Fácil: exponha v1 e v2 de um recurso.
• Médio: deprecie v1 e confirme os headers de aviso.
• Desafio: implemente versionamento por media type e compare com o por URL.

9. Resumo#

Asp.Versioning habilita múltiplas estratégias de versionamento, depreciação e relatório de versões. Versione apenas em mudanças incompatíveis e comunique a depreciação.

10. Próximos Passos#

Módulo 38: caching HTTP com Cache-Control e ETag.

11. Referências#

• Repositório oficial — Asp.Versioning (.NET)
• Microsoft Learn — Versão de APIs web
• Microsoft — Diretrizes de versionamento REST