Versionamento

Cada endpoint responde em dois caminhos:

POST /api/v1/payments/create     versioned, use this
POST /api/payments/create        unversioned, permanently supported

Hoje, ambos executam exatamente o mesmo código.

Use o caminho com versão. É a única forma de ter a certeza de que uma alteração futura não o vai afetar. Uma integração no caminho sem versão recebe aquilo que “sem versão” representar nesse momento, que hoje é a v1 e um dia poderá não ser.

O caminho sem versão é um alias permanente, não uma descontinuação. Não vai ser removido. Existem integrações que não podem ser atualizadas, como plugins que os comerciantes atualizam ao seu próprio ritmo ou nunca, e essas têm de continuar a funcionar.

Cada resposta indica que versão a serviu:

X-API-Version: v1

GET /api/versions lista as versões que existem e a versão para a qual o seu pedido foi resolvido.

O que conta como alteração incompatível

Avisamos antes de fazer alterações incompatíveis. Essa promessa só tem significado se estivermos de acordo quanto ao que o termo quer dizer.

Lançado sem aviso, na versão atual:

• um novo endpoint
• um novo campo opcional no pedido
• um novo campo na resposta
• um novo valor de enum que se espera que os clientes tolerem
• uma regra de validação flexibilizada para aceitar mais dados de entrada
• uma correção a uma resposta que nunca correspondeu ao comportamento documentado
• qualquer alteração sem efeito visível nos pedidos ou nas respostas

Exige uma nova versão:

• remover ou mudar o nome de um campo do pedido ou da resposta
• alterar o tipo ou o significado de um campo
• alterar o código de estado de um resultado existente
• tornar obrigatório um campo opcional
• tornar a validação mais restritiva, de modo que dados antes aceites passem a ser rejeitados
• remover um endpoint ou alterar o seu caminho
• alterar o que acontece quando um campo é omitido

A regra de fundo: se uma integração que funciona hoje deixar de funcionar, ou passar a comportar-se de forma diferente sem alterar o seu próprio código, a alteração é incompatível.