Versões e compatibilidade

A API tem uma única versão principal, /v1, e ela só cresce. Uma integração escrita hoje continua funcionando conforme novos recursos chegam: nada do que ela usa é renomeado, removido ou ganha um novo significado.

O número da versão

A API tem um número de versão como 1.62.0. Ele muda a cada lançamento:

• o número da versão secundária, quando algo é acrescentado: um endpoint, um campo, um evento;
• o número da correção, quando uma descrição ou o texto de uma mensagem é corrigido e nada mais muda.

Você pode ler a qualquer momento a versão que um endereço atende:

GET /v1/health também tem um version, mas é a versão do lançamento do Sursa que atende o endereço, não a versão da API.

Você não escolhe uma versão secundária: toda requisição é atendida pela versão atual. Graças às regras abaixo, isso é seguro.

O que pode mudar em /v1

Estas alterações podem chegar em qualquer versão secundária. Escreva sua integração de modo que elas não a quebrem:

• Novos endpoints.
• Novos parâmetros e campos de requisição opcionais. As requisições sem eles se comportam como antes.
• Novos campos em respostas, objetos e eventos.
• Novos valores de enumerações nas respostas, como um novo status de cartão ou um novo tipo de evento.
• Novos códigos de erro e novos cabeçalhos de resposta.
• Limites que ficam menos rígidos: um comprimento máximo maior, um intervalo mais amplo.
• Textos message de erros e descrições com nova redação.

O que o seu código precisa tolerar

• Ignore os campos que você não conhece. Não falhe quando uma resposta tiver mais campos do que o esperado e não use esquemas rígidos que os rejeitem.
• Aceite valores de enumeração que você não conhece. Toda enumeração de uma resposta pode crescer. Trate um valor desconhecido como “outro”, e não como um erro.
• Ignore os tipos de evento que você não conhece, tanto nos webhooks quanto nos streams.
• Trate os códigos de erro desconhecidos pelo status HTTP: veja Erros.
• Não dependa da ordem dos campos nos objetos JSON nem do texto exato das mensagens.

O que nunca muda em /v1

• Um caminho, um parâmetro, um campo ou um valor de enumeração nunca é renomeado nem removido.
• O tipo de um campo nunca muda, e um campo nunca ganha um novo significado, como novas unidades.
• Uma requisição aceita hoje não é rejeitada depois.
• O código de status de uma resposta bem-sucedida continua o mesmo.
• Os códigos de erro mantêm o significado, e o campo detail das respostas de erro mantém a forma.
• Os tipos de evento nunca são renomeados nem removidos, e o data deles só ganha campos.

Alterações incompatíveis

Se algum dia for necessária uma alteração incompatível, ela será lançada como uma nova versão principal, como /v2, ao lado de /v1. /v1 continua funcionando sem mudanças, e as duas funcionam lado a lado.

Quando uma rota vai ser desativada:

1. Ela é marcada como deprecated na especificação e aparece no histórico de alterações com a data em que será desligada.
2. As respostas dela trazem os cabeçalhos Deprecation: true e Sunset: <date>.
3. Ela continua funcionando por pelo menos 180 dias depois do anúncio. As organizações cujas chaves de API a usam são avisadas por escrito com pelo menos 90 dias de antecedência.
4. Depois da data de desativação, ela responde 410 com o código api.gone por mais 90 dias.

Fique atento ao cabeçalho Deprecation nos seus logs ou no monitoramento: ele é o primeiro sinal de que uma rota que você usa vai deixar de existir.

Como se manter informado

O histórico de alterações deste portal lista cada lançamento, com o que foi acrescentado e o que se tornou obsoleto. Antes de atualizar a sua integração, compare o código dela com as entradas publicadas desde a versão para a qual você a escreveu.