Versionamento e depreciação
O que é estável no contrato /v1, o que pode mudar sem aviso de versão, e como uma mudança incompatível seria anunciada e convivida.
A versão da API está no caminho: /v1. Dentro de /v1, o contrato só recebe mudanças aditivas; uma mudança incompatível criaria /v2, anunciada no changelog e por e-mail aos titulares de chave, com período de convivência entre as duas versões. Não há header de versão. A versão do documento OpenAPI publicado é 1.0.0.
O que é estável em /v1
- Os caminhos e métodos das operações, os nomes dos parâmetros e o significado de cada um.
- Os nomes, tipos e a nulabilidade dos campos da resposta;
nullcontinua significando ausência de dado, nunca chave omitida. - O enum de
error.codee o status HTTP de cada código. - Os headers
X-Request-Id,X-Client-Request-Id,X-Credits-*,X-RateLimit-*eRetry-After, e a regra de quando cada um vem, resposta por resposta. - A regra de cobrança: só respostas
200são cobradas, e o peso de cada operação está em/precos.
O que pode mudar sem nova versão
Mudanças aditivas, sempre registradas no changelog:
- Campo novo na resposta, em qualquer objeto.
- Valor novo em um enum de dados (uma nova situação cadastral, um novo código de motivo). Trate valores desconhecidos como texto e não falhe.
- Código de erro novo, sempre com um status HTTP já existente. Trate código desconhecido como erro genérico.
- Filtro novo na busca, ferramenta nova no MCP, endpoint novo.
- Descrições, exemplos e a documentação.
Clientes robustos ignoram campos que não conhecem e não dependem da ordem das chaves no JSON.
Como uma mudança incompatível seria feita
Remover ou renomear campo, mudar tipo, mudar o significado de um parâmetro ou o status de um código de erro é incompatível. Se um dia for necessário: a mudança nasce em /v2, /v1 continua respondendo durante um período de convivência mínimo de 90 dias, e o changelog e o e-mail aos titulares de chave anunciam a data de encerramento. Nenhuma mudança incompatível é feita dentro de /v1.
Estado atual do contrato
O documento OpenAPI publicado em /openapi/openapi.json está na versão 1.0.0. Enquanto o sufixo draft existir, o contrato pode receber ajustes antes da abertura pública, todos registrados no changelog; a partir da versão sem sufixo valem as regras acima. Desde o draft.4 o documento é gerado a partir dos testes de contrato da própria implementação, e o site o publica sem alteração estrutural.
Descoberta no host da API
Quatro caminhos sem chave no host da API descrevem o contrato para pessoas e agentes, com cache público e disponíveis também na janela de manutenção da base: GET /openapi.json (este contrato, em JSON), GET /robots.txt, GET /llms.txt e GET /.well-known/api-catalog (um linkset, RFC 9727, com o contrato e a documentação). Os quatro estão declarados no próprio contrato e aparecem na referência gerada. A cópia versionada do contrato publicada neste site é /openapi/openapi.json; a versão servida pela API e esta cópia são a mesma a cada publicação.
Relacionados
- Changelog.
- Referência gerada do OpenAPI: o contrato como está publicado.