o versionamento é a capacidade de adicionar, remover e alterar funcionalidades em uma API, sem afetar a interface existente e sem quebrar a aplicação para os clientes que já a consomem. é uma prática essencial para garantir a evolução controlada e a compatibilidade das APIs ao longo do tempo.


métodos de versionamento

versionamento por URL

por subdomínio

especifica a versão logo no início da URL, usando subdomínios.

  • exemplo: https://v1.host/api/...

por path param

abordagem mais utilizada, permite fácil navegação entre as versões. especifica a versão após a base URL da API, utilizando path parameters.

  • exemplo: https://host/api/v1/...

por query param

padrão que foi muito utilizado antigamente, mas pode prejudicar a elegibilidade da URL e a navegação para outras versões. utiliza query parameters para buscar a versão.

  • exemplo: https://host/api/recurso/.../1?version=1.0

versionamento por header param

por accept

define a versão no cabeçalho Accept do header param da requisição.

por custom header param

permite definir um cabeçalho personalizado para especificar a versão. a URL permanece intacta, mas é necessário cuidado ao realizar a requisição para incluir o cabeçalho customizado.