Versionamento de API
Como evoluir um contrato sem quebrar quem já o usa, e quais mudanças quebram de verdade.
Versionar uma API é a forma de mudá-la sem quebrar os sistemas que já dependem dela. A maior parte do trabalho, porém, é evitar precisar de uma versão nova.
Depois de publicada, uma API tem clientes que você não controla e que não atualizam no seu ritmo. Uma mudança que parece inofensiva no servidor pode derrubar a integração de um parceiro.
- Remover ou renomear campos quebra clientes; acrescentar costuma ser seguro.
- Acrescentar um valor novo numa lista fechada, como um status, quebra clientes tipados.
- Clientes tolerantes ignoram o que não conhecem.
- Uma versão nova é o último recurso, com prazo e aviso para desligar a antiga.