Conceitos

Versões e alterações

O compromisso de estabilidade da API e o registo das alterações.

Cada resposta traz o cabeçalho X-Mucanda-Api-Version com a versão que respondeu. A versão actual é a 1.

#O que pode mudar sem aviso

• Campos novos nas respostas. O seu programa tem de ignorar os campos que não conhece.
• Parâmetros opcionais novos e operações novas.
• Valores novos nas listas abertas (códigos de erro, tipos de documento, estados).
• Melhorias de desempenho e correcções que não alterem o que está documentado.

#O que só muda numa versão nova

• Remover ou renomear um campo, uma operação ou um código de erro.
• Mudar o tipo ou o significado de um campo.
• Tornar obrigatório um campo que era opcional.

Uma mudança assim faz-se numa versão nova (/api/v2/…) e a versão anterior mantém-se, no mínimo, 12 meses depois de a nova ser anunciada. Os endereços descontinuados passam a responder com os cabeçalhos Deprecation e Sunset, e os titulares das chaves que os usam são avisados por e-mail.

#Registo de alterações