C# Academy · Aula

Estratégias de versionamento de API

Faça o versionamento pela URL, pelo cabeçalho e pela string de consulta.

Estratégias de versionamento de API é uma aula grátis de C# Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de C# Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de C# Academy inclui 4 aulas no total.

Por que versionar uma API?

Quando os clientes passam a depender da sua API, você não pode quebrar o contrato dela. O versionamento permite lançar alterações incompatíveis em uma nova versão, enquanto os clientes antigos continuam funcionando com a versão anterior.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Versionamento pelo caminho da URL

A estratégia mais visível coloca a versão no caminho. Ela não deixa margem para ambiguidade e facilita o roteamento, a navegação e o armazenamento em cache.

GET /api/v1/products
GET /api/v2/products

Versionamento por cadeia de consulta

A versão é enviada como um parâmetro de consulta. As URLs permanecem estáveis, e um parâmetro ausente pode usar como padrão a versão mais recente ou uma versão fixa.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Versionamento por cabeçalho

Um cabeçalho de solicitação personalizado transporta a versão, mantendo a URL limpa. A desvantagem é que ele não aparece na barra de endereços do navegador e é mais difícil de testar manualmente.

GET /api/products
X-Api-Version: 2.0

Versionamento por tipo de mídia

Também chamado de negociação de conteúdo. A versão é incorporada ao tipo de mídia do cabeçalho Accept. É a opção mais alinhada ao REST, mas a menos fácil de descobrir.

GET /api/products
Accept: application/json;v=2.0

Comparando as estratégias

Cada estratégia equilibra a facilidade de descoberta e a limpeza da URL:

Caminho da URL: mais fácil de descobrir, mas polui as URLs.
Cadeia de consulta: URLs estáveis e padrões fáceis.
Cabeçalho: URLs limpas, mas oculto dos navegadores.
Tipo de mídia: REST mais purista, mas mais difícil de usar.

// Many teams pick URL path for public APIs

Versionamento semântico de APIs

As versões de API geralmente usam apenas a versão principal (v1, v2). Reserve as versões secundárias para alterações aditivas e compatíveis, que os clientes antigos possam ignorar.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Descontinuação

Nunca remova uma versão antiga de forma abrupta. Marque-a como obsoleta, divulgue uma data de encerramento e informe os clientes por meio de cabeçalhos.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Versão padrão

Decida o que acontece quando um cliente não envia uma versão. As opções comuns são: assumir a versão mais recente, assumir a v1 ou rejeitar a solicitação. Ser explícito evita surpresas.

// Strategy: unversioned request -> treat as v1.0

Versionando os elementos certos

Versione o contrato (rotas e formatos de solicitação/resposta), não os detalhes internos da implementação. Um ponto de extremidade v2 pode compartilhar a maior parte da lógica de negócio com a v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Combinando estratégias

A biblioteca de versionamento do ASP.NET Core pode ler a versão de várias fontes ao mesmo tempo, permitindo que os clientes escolham a opção mais conveniente. Você fará essa configuração a seguir.

// Accept version from URL OR header OR query

Verificação rápida

Teste seu entendimento sobre as estratégias de versionamento.

Recapitulação

Você conheceu as estratégias de versionamento de APIs:

caminho da URL, cadeia de consulta, cabeçalho e tipo de mídia.
Cada uma equilibra a facilidade de descoberta e a limpeza da URL.
Versione o contrato, faça a descontinuação de forma gradual e defina um padrão.

Próximo tópico: configurando Asp.Versioning no ASP.NET Core.

Perguntas Frequentes

A aula “Estratégias de versionamento de API” é grátis?

Sim — o texto completo de “Estratégias de versionamento de API” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de C# Academy, atualize para CoddyKit PRO. O curso de C# Academy inclui 4 aulas no total.

O que vou aprender em “Estratégias de versionamento de API”?

Faça o versionamento pela URL, pelo cabeçalho e pela string de consulta. Você pratica C# Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar C# Academy?

Nenhuma experiência prévia é necessária. C# Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Estratégias de versionamento de API”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de C# Academy?

Sim. Cada aula de C# Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para C# Academy