Versionamento e compatibilidade

Há uma só versão, v1, e ela só muda de forma compatível. Isto é o que você pode dar como certo, e o que o seu cliente tem que tolerar.

​

O que não muda dentro de v1

• Os paths e os métodos das cinco operações.
• Os campos obrigatórios de cada requisição e de cada resposta: não são removidos nem mudam de tipo.
• Os momentos (surface) e os sete tipos de sinal.
• A forma comum dos erros: type, title, status, detail, code, request_id, com as extensões no nível raiz.
• Os prefixos dos ids.

​

O que pode mudar sem aviso

O SDK já faz isso: os tipos deixam passar campos desconhecidos, CrossUpApiError guarda em extensions o que não conhece, e reason_codes é string[].

​

O incompatível, e como é avisado

Remover um campo, mudar um tipo, um path ou o significado de um valor. Nada disso entra em v1. Se for preciso, sai como v2 em outro path, v1 continua viva, e a mudança é anunciada em Mudanças antes de sair.

​

Qual versão do contrato você está vendo

Esta referência é gerada do contrato OpenAPI 3.1, e cada mudança fica em Mudanças com a data e a operação que tocou.