API Versioning
Versionamento de API
O versionamento de API é um plano para nomear, alterar, suportar e descontinuar contratos de API sem quebrar os clientes. Não existe um URL ou estilo de cabeçalho que toda API deva usar.
Outro exemplo
Uma API de folha de pagamento publica o contrato OpenAPI `2026-07` e mantém os clientes `/v1` funcionando. Adicionar um campo opcional não os quebra. Alterar `netPay` de centavos inteiros para decimal exige um novo contrato principal. Também são necessários guias de migração, cabeçalhos de descontinuação, dados de uso e uma data de aposentadoria.
Partes principais
- 01Identificador de contrato
- 02Regras de compatibilidade
- 03Deprecação e migração
Use-o quando
Defina regras de compatibilidade, tipos de alteração, método de descoberta, período de suporte e política de descontinuação primeiro. Em seguida, escolha um caminho, tipo de mídia ou estilo de cabeçalho.
Não o use quando
Não crie uma nova versão da API para cada lançamento. Não prometa suporte para sempre sem dados de uso e uma forma de descontinuar versões antigas.
Nome usado no código
explicit compatibility policy + versioned OpenAPI document + deprecation and sunset lifecycle Antes de lançar
Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback.
Outcome: Complete the task with Versionamento de API (API Versioning). User context: Uma API de folha de pagamento publica o contrato OpenAPI `2026-07` e mantém os clientes `/v1` funcionando. Adicionar um campo opcional não os quebra. Alterar `netPay` de centavos inteiros para decimal exige um novo contrato principal. Também são necessários guias de migração, cabeçalhos de descontinuação, dados de uso e uma data de aposentadoria. Technical concept or control: Versionamento de API (API Versioning). Why it fits: Defina regras de compatibilidade, tipos de alteração, método de descoberta, período de suporte e política de descontinuação primeiro. Em seguida, escolha um caminho, tipo de mídia ou estilo de cabeçalho. Do not use it when: Não crie uma nova versão da API para cada lançamento. Não prometa suporte para sempre sem dados de uso e uma forma de descontinuar versões antigas. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): Nenhum padrão oficial único controla todo o termo. Seu significado pode mudar entre equipes, plataformas ou frameworks. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.
Conferir este pedido
Review how Versionamento de API (API Versioning) is used now. Definition: O versionamento de API é um plano para nomear, alterar, suportar e descontinuar contratos de API sem quebrar os clientes. Não existe um URL ou estilo de cabeçalho que toda API deva usar. Release checks: Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback. Before changing code, list the evidence, gaps, severity, and the smallest safe fix.