ETAR · API v1
Política de versionamento e descontinuação da API da ETAR
A API de conteúdo público usa versões principais na URL. /api/v1/content está ativa. Não foi anunciada nenhuma data de descontinuação ou encerramento.
Compatibilidade dentro da v1
Os significados e tipos dos campos existentes e o acesso público permanecem compatíveis dentro da v1. Campos e links opcionais podem ser adicionados; os clientes devem ignorar campos desconhecidos. Páginas e documentos publicados podem mudar ou ser retirados por revisão editorial. Uma lista vazia é válida e não significa que a API esteja indisponível.
Mudanças incompatíveis e migração
Uma mudança planejada e incompatível no contrato exige uma nova URL de versão principal, como /api/v2/content. Antes de um encerramento planejado, a ETAR publicará nesta página os endpoints afetados, a versão substituta, as instruções de migração e as datas de descontinuação e encerramento. O prazo de aviso será informado nesse anúncio; atualmente não há um período fixo de suporte garantido. Correções de segurança ou privacidade podem exigir restrições imediatas.
Sinais de Deprecation e Sunset
As respostas incluem um link para esta política por meio de Link: <policy URL>; rel="deprecation"; type="text/html", conforme definido na RFC 9745. Quando uma descontinuação for anunciada, as respostas afetadas usarão a data de campo estruturado Deprecation da RFC 9745: @ seguido de segundos Unix. Quando um encerramento for programado, Sunset usará uma data HTTP em GMT, conforme definido na RFC 8594. A data de encerramento não será anterior à data de descontinuação.
As respostas da v1 ativa atualmente omitem os dois cabeçalhos de data. Os clientes devem seguir o link da política e verificar esses cabeçalhos nas respostas de sucesso e erro, inclusive em HEAD. Devem migrar antes de um encerramento anunciado e nunca deduzir uma data de encerramento a partir da ausência de um cabeçalho.
Escopo e notas de versão
Esta política abrange o contrato da API REST. O MCP negocia suas próprias versões de protocolo; as versões da CLI seguem um versionamento semântico separado. Nenhum deles altera o escopo de somente leitura da API. A versão do documento OpenAPI descreve sua revisão, enquanto /v1/ identifica a versão principal estável da API.
- API v1: ativa; descontinuação: nenhuma; encerramento: nenhum.
- OpenAPI 1.1.0: adiciona links para o MCP, o download da CLI e esta política. Os campos e as operações existentes permanecem compatíveis.
Guia de integração da API, do MCP e da CLI da ETAR · OpenAPI