Versionamento e changelog

A versão está no caminho

Todas as operações ficam em https://dash.halver.com.br/api/v1. A referência OpenAPI (YAML e JSON) traz a versão do documento em info.version.

Onde as mudanças são anunciadas

Toda mudança na API pública entra no changelog, com a data. A referência e os arquivos OpenAPI são gerados a cada publicação desta documentação a partir do mesmo contrato que os testes da plataforma conferem contra o servidor, então a referência que você lê é a que o servidor responde.

Para acompanhar:

• leia o changelog;
• guarde a referência OpenAPI que o seu cliente usa e compare com a publicada (um diff dos arquivos, ou uma ferramenta de comparação de OpenAPI).

Escreva um cliente que tolera acréscimos

A v1 recebe acréscimos: operações, campos nas respostas, parâmetros opcionais, valores novos em campos de estado. Para o seu cliente não quebrar com eles:

• ignore campos que não conhece nas respostas;
• trate um valor desconhecido de status como “ainda não terminou” ou “estado que eu não sei tratar”, nunca como erro fatal;
• decida pelos códigos de erro em code e pelo status HTTP, não pelo texto de detail (Erros);
• respeite Retry-After e os cabeçalhos RateLimit em vez de números fixos (Limites de uso).