Versionamento de API

Existem três abordagens principais. O versionamento por URI (/v1/, /v2/) é o mais comum: os clientes especificam explicitamente a versão em cada URL de solicitação. Simples e altamente visível, mas as rotas que a equipe deve manter em paralelo crescem a cada versão principal. O versionamento por cabeçalho (API-Version: 2024-01-01) mantém a URL limpa e permite o versionamento baseado em data (modelo da Stripe), onde cada versão da API é nomeada após uma data e os clientes são atualizados para novos padrões no aniversário de sua própria conta. O versionamento por parâmetro de consulta (?version=2) é o mais simples, mas muitas vezes considerado o menos limpo. A maioria das APIs SaaS usa o versionamento por URI para APIs públicas. Independentemente do mecanismo, os principais compromissos com os clientes são: por quanto tempo as versões antigas serão suportadas? (o padrão da indústria é de 12 a 24 meses após o lançamento de uma nova versão); como as breaking changes são definidas e comunicadas? (uma definição formal de "breaking change" evita debates durante a descontinuação); e qual é o caminho de migração? (fornecer guias de migração claros com exemplos de código).

A descontinuação de API é um evento de confiança do cliente — mal feita, gera um sentimento negativo significativo, mesmo quando a melhoria subjacente do produto é positiva. Melhores práticas para a descontinuação de API SaaS: anunciar a descontinuação com 12+ meses de antecedência (mínimo de 6 meses para endpoints de baixo uso); fornecer uma data de desativação concreta (cronogramas de descontinuação ambíguos criam falsa segurança); enviar notificações direcionadas a cada cliente que usa ativamente o endpoint descontinuado (identificável a partir dos logs da API — 'Prezado(a) [Empresa], nossos registros mostram que você está chamando /v1/users — este endpoint será desativado em [data]. Veja como migrar:'); publicar um guia de migração detalhado com exemplos de código antes/depois; oferecer um modo de compatibilidade ou período de shimming onde a nova versão traduz do esquema antigo; e criar um painel de uso de endpoint descontinuado visível para os clientes em suas configurações de administrador, mostrando seu uso e o tempo restante.

As descontinuações de API geram de forma confiável picos de tickets de suporte — clientes migram no último minuto, problemas de integração surgem e alguns clientes perdem completamente a descontinuação. Estratégias de mitigação: desativar em ondas em vez de tudo de uma vez (desabilitar para 5% dos clientes afetados selecionados aleatoriamente duas semanas antes da desativação completa, para que os problemas surjam com um volume gerenciável antes do impacto total); aumentar a equipe de suporte para a janela de descontinuação (agendar horas adicionais de agentes nas duas semanas antes e depois da data de desativação); pré-construir uma macro do Zendesk com o guia de migração e soluções de erros comuns, permitindo uma resolução rápida no primeiro contato por agentes de Nível 1 sem escalonamento de engenharia; criar uma visualização dedicada 'API Migration' no Zendesk para que esses tickets sejam triados pelos seus agentes mais tecnicamente capazes; e postar uma atualização de status em tempo real na sua página de status do desenvolvedor para o dia da desativação, com monitoramento para picos de erros relacionados à migração.