Política de Versionamento da API

Prefixo de Versão

Todos os endpoints públicos utilizam o prefixo /v1/ no caminho. Mudanças incompatíveis (breaking changes) só serão introduzidas em incrementos de versão major (ex.: /v2/).

Seleção de Versão

O cliente seleciona a versão da API pela URL. Não há negociação por header — a versão é determinada exclusivamente pelo prefixo do caminho:

https://api.signdocs.com.br/v1/transactions
https://api.signdocs.com.br/v2/transactions   (futuro)

• Cada versão da API possui seu próprio conjunto de rotas e handlers.
• SDKs oficiais mapeiam automaticamente para a versão correta da API. A versão major do SDK corresponde à versão major da API (ex.: SDK 2.x utiliza /v2/).
• Não há parâmetro de query nem header Accept-Version para seleção de versão.

Header API-Version

Toda resposta inclui o header API-Version indicando a versão atual da API:

API-Version: 1.0

Este header é informativo e não participa da seleção de versão. Ele permite que o cliente confirme qual versão está sendo servida.

Coexistência de Versões

Quando uma nova versão major é lançada, a versão anterior continua disponível:

• /v2/ coexiste com /v1/ durante todo o período de sunset da versão anterior.
• Cada versão possui handlers Lambda independentes — não há ramificação condicional de código baseada em versão.
• A especificação OpenAPI de cada versão é mantida separadamente (ex.: openapi-v1.yaml, openapi-v2.yaml).
• Ambas as versões compartilham a mesma tabela DynamoDB, buckets S3 e filas SQS. O isolamento ocorre na camada de roteamento e nos handlers.

Ciclo de Vida de Versão

O ciclo de vida de uma versão da API segue estas fases:

1. Ativa — versão atual, recomendada para todos os consumidores.
2. Depreciada — versão anterior após o lançamento de uma nova versão major. Recebe headers Deprecation e Sunset (RFC 8594). Continua funcional.
3. Sunset — período de 6 meses entre a deprecação e a remoção. Patches de segurança são aplicados durante este período.
4. Removida — versão desativada. Requisições retornam 410 Gone.

Janela mínima de sunset: 6 meses a partir da data de deprecação.

Patches de segurança durante sunset: correções críticas de segurança são aplicadas à versão depreciada durante todo o período de sunset.

Frequência de versões major: versões major são raras — estimativa de uma a cada 2 a 5 anos. A API prioriza estabilidade e evolução por adições não incompatíveis.

Headers de Deprecação e Sunset (RFC 8594)

Quando um endpoint ou versão está agendado para remoção, a API retorna headers padrão RFC 8594:

Header	Formato	Descrição
Deprecation	true ou @<unix-timestamp>	Indica que o endpoint está depreciado. O timestamp marca quando a deprecação começou.
Sunset	HTTP-date (RFC 7231)	Data após a qual o endpoint será removido.
Link	<substituto>; rel="successor-version"	Aponta para o endpoint substituto, quando disponível.

Exemplo

HTTP/1.1 200 OK
API-Version: 1.0
Deprecation: @1725148800
Sunset: Tue, 01 Sep 2026 00:00:00 GMT
Link: <POST /admin/tenants/{id}/credentials (com campo mode)>; rel="successor-version"

Notificações via Webhook

Clientes podem se inscrever no evento API.DEPRECATION_NOTICE para receber alertas proativos quando endpoints são depreciados ou estão próximos da data de sunset.

Endpoints Independentes de Versão

Alguns endpoints são compartilhados entre todas as versões da API e não possuem prefixo de versão:

Endpoint	Descrição
/oauth2/token	Emissão de token de acesso OAuth2
/health	Verificação de saúde do sistema
/health/history	Histórico de verificações de saúde
/v1/verify/{evidenceId}	Verificação pública de evidência (compartilhado)

Estes endpoints são estáveis e não são afetados por mudanças de versão da API.

Mudanças Incompatíveis (Breaking Changes)

Uma mudança incompatível é definida como:

• Remoção de um endpoint ou método HTTP
• Remoção ou renomeação de um campo de request/response
• Alteração do tipo ou regras de validação de um campo existente
• Alteração dos requisitos de autenticação

Mudanças não incompatíveis (adição de campos opcionais, novos endpoints, novos valores de enum) podem ser introduzidas dentro da versão atual sem incremento de versão.

Implantação de Nova Versão Major

Quando uma nova versão major é implantada, o processo interno segue esta estrutura:

1. Novos handlers são criados em src/handlers/v2/ — código completamente separado da v1.
2. Novas rotas CDK são adicionadas ao API Gateway com o prefixo /v2/.
3. Especificação OpenAPI separada é criada em openapi/openapi-v2.yaml.
4. Handlers da v1 continuam inalterados e servindo requisições normalmente.
5. Headers de deprecação são adicionados às respostas da v1.

Esta abordagem garante que a v1 permanece estável e testada enquanto a v2 é desenvolvida e implantada de forma independente.

Endpoints Atualmente Depreciados

Endpoint	Depreciado desde	Data de Sunset	Substituto
POST /admin/tenants/{id}/mode	2025-09-01	2026-09-01	Modo por credencial via POST /admin/tenants/{id}/credentials com campo mode