Compatibilidade e versionamento

A API DUST é versionada no caminho — todos os endpoints se encontram em /api/v1. Dentro de uma versão, fazemos evoluir continuamente a API, mas de acordo com regras rigorosas: por predefinição, as alterações são aditivas, tudo o que possa interromper uma integração bem comportada passa primeiro por um período de descontinuação e a especificação OpenAPI publicada constitui, em qualquer momento, a declaração oficial do contrato.

Esta página define o que significa uma integração «bem comportada» e o que prometemos em contrapartida.

O que pode mudar sem aviso prévio

Estas alterações são consideradas retrocompatíveis. Podem surgir em qualquer versão e a sua integração tem de as tolerar:

• Novos endpoints e novas operações em caminhos existentes.
• Novos parâmetros de pedido, cabeçalhos e campos de corpo opcionais. Os pedidos existentes continuam a funcionar sem alterações.
• Novos campos nas respostas. Os objetos aumentam ao longo do tempo.
• Novos valores em campos enumerados — são adicionados novos tipos de evento, estados e categorias à medida que o produto evolui.
• Novos códigos de erro para modos de falha que anteriormente eram apresentados com um código genérico.
• Documentação, texto de message dos erros e ordenação dos campos. As cadeias legíveis por pessoas não fazem parte do contrato; a ordem dos membros JSON nunca é significativa.

Escrever uma integração que se mantém compatível

As regras acima são seguras se o seu cliente seguir as práticas padrão de leitura tolerante:

• Ignore os campos de resposta que não reconhece. Nunca falhe devido a membros inesperados e não utilize uma validação rigorosa do esquema que rejeite campos desconhecidos.
• Tolere valores de enumeração desconhecidos. Crie ramificações para os valores que processa e prossiga corretamente perante os que não processa.
• Crie ramificações com base no code do erro, nunca no message. Os códigos são identificadores estáveis; as mensagens são localizadas e podem ser reformuladas. Consulte Convenções dos pedidos.
• Trate os IDs e os cursores de paginação como cadeias opacas. Guarde-os e reutilize-os; nunca os analise nem construa.
• Utilize apenas o que está documentado na especificação publicada. Os endpoints, campos e comportamentos que não constem da especificação OpenAPI pública não beneficiam de qualquer garantia de compatibilidade.

Uma integração que siga estas regras não é afetada por alterações aditivas e é o tipo de integração protegido pelas garantias abaixo.

O que consideramos uma alteração incompatível

Não efetuamos nenhuma das seguintes alterações a uma operação /api/v1 publicada sem aplicar o processo de descontinuação descrito abaixo:

• Remover ou mudar o nome de um endpoint, parâmetro de pedido ou campo de resposta.
• Alterar o tipo ou o formato de um campo.
• Tornar obrigatório um dado de entrada opcional de um pedido ou restringir os valores aceites por um dado de entrada.
• Remover um valor de um campo enumerado.
• Alterar o code do erro ou o estado HTTP devolvido para um modo de falha existente e documentado.
• Exigir um nível de autorização superior ou uma nova permissão para uma operação existente.
• Alterar substancialmente a semântica de uma operação, mesmo que a sua estrutura permaneça inalterada.

Descontinuação

Quando é necessário retirar ou reformular algo, esse elemento é primeiro descontinuado:

• A operação ou o campo é marcado como deprecated: true na especificação OpenAPI publicada e a descontinuação é assinalada nesta documentação.
• A funcionalidade descontinuada continua a funcionar, sem alterações, durante pelo menos 90 dias após o anúncio.
• Sempre que exista uma alternativa, é disponibilizada uma substituição documentada antes ou no momento da descontinuação.

Acompanhe a especificação, não as comunicações na rede

A especificação OpenAPI publicada em /openapi.json reflete sempre o contrato atual, incluindo os marcadores de descontinuação. Compará-la entre as revisões da sua integração é a forma mais fiável de identificar o que mudou.

Versionamento

Por definição, as novas versões principais são raras. A /api/v1 evolui de forma aditiva; apenas introduziríamos uma /api/v2 para uma reformulação que não pudesse ser expressa de forma compatível e, nesse caso, a /api/v1 continuaria a ser suportada durante um período de migração longo e anunciado explicitamente — nunca seria removida após o período de descontinuação indicado acima.

Consulte também

• Convenções dos pedidos — o contrato de pedidos partilhado ao qual se aplicam estas garantias.
• Autenticação e chaves de API — contas de serviço e períodos de validade dos tokens.
• Referência completa da API — gerada a partir da especificação publicada.