Skip to main content
A versão maior está no path: /v1. Dentro de /v1 o contrato muda apenas de forma aditiva:
  • novos endpoints;
  • novos parâmetros de query opcionais;
  • novos campos nas respostas;
  • novos códigos de erro para situações novas.
Construa o cliente para estes nunca o quebrarem: ignore campos de resposta que não conhece e trate um código de erro desconhecido pelo respetivo estado HTTP.

​
Alterações incompatíveis

Todo o resto é uma alteração incompatível: remover ou renomear um campo ou endpoint, mudar o tipo ou significado de um campo, adicionar um valor a um enum existente como status, ou tornar um parâmetro obrigatório. Uma alteração incompatível tem pelo menos 6 meses de aviso no registo de alterações, com o que muda, o que precisa de fazer e a primeira data em que o comportamento anterior deixa de existir. Quando possível, chega numa nova versão maior (/v2) enquanto /v1 continua a funcionar até essa data.

​
Onde as alterações são anunciadas

Cada alteração publicada da API tem uma entrada datada no registo de alterações. Produção e staging mudam em conjunto, com staging atualizado primeiro.