Política de versionamento
Versão maior no caminho
Seção intitulada “Versão maior no caminho”A versão maior da API faz parte do caminho da URL: /v1. Uma mudança incompatível só chega numa nova versão maior (/v2); a /v1 nunca é alterada de forma incompatível.
Mudanças compatíveis chegam sem aviso
Seção intitulada “Mudanças compatíveis chegam sem aviso”Estas mudanças não quebram a compatibilidade e podem entrar na /v1 a qualquer momento, sem aviso prévio:
- operação nova;
- campo novo na resposta;
- parâmetro opcional novo;
- valor novo em um enum;
- código de erro novo;
- cabeçalho novo.
O que a sua integração precisa fazer
Seção intitulada “O que a sua integração precisa fazer”Ignore campos e valores que você não conhece, em vez de falhar ao encontrá-los. Um campo novo na resposta, um valor novo num enum ou um código de erro novo não podem derrubar a sua integração: trate o valor desconhecido como um caso genérico e siga em frente.
Changelog
Seção intitulada “Changelog”Toda release que altera a especificação OpenAPI (openapi.json) ganha uma entrada datada no changelog. Para saber como uma operação é retirada, veja a política de descontinuação.