Integração e API
Versionamento de API
Quando uma mudança altera campos, semântica ou comportamento de modo incompatível, o versionamento de API separa contratos para permitir migração gradual. Azure API Management suporta identificadores por caminho, query ou header; APIs também usam media types e datas. A versão não deve mudar a cada campo opcional. O custo é manter múltiplos contratos; o benefício é não quebrar aplicativos e hubs instalados. Para a residência, uma integração antiga continua operando enquanto o cliente é atualizado.
🔀 Tipos de Comunicação
PATH
Versão no caminho da URL
O cliente chama `/v1/devices` ou `/v2/devices`. É explícito, fácil de roteador, documentar e observar. API gateways criam conjuntos de versão. Links e caches distinguem naturalmente. A desvantagem é que a versão parece parte da identidade do recurso. Migrar exige alterar URLs. Serviços podem manter v1 e v2 em paralelo. O código interno deve evitar duplicação completa: adaptadores de contrato podem mapear para um domínio comum. Um caminho v2 não deve existir sem diferença relevante. Pequenas adições compatíveis ficam na mesma versão. A política precisa definir o que é breaking: remover campo, mudar tipo, alterar unidade, tornar obrigatório, mudar enum ou semântica.
HEADER
Versão em cabeçalho ou media type
O cliente usa `Api-Version: 2026-07-01` ou `Accept: application/vnd.livsmart.device-v2+json`. A URL permanece estável. Content negotiation é alinhada ao HTTP. A configuração é menos visível em navegador, logs e links. Caches precisam incluir `Vary`. Proxies e gateways devem preservar. Uma data pode representar contrato lançado em determinado dia, como APIs que usam versões datadas. O servidor escolhe default somente com cautela. Um cliente que omite versão pode mudar de comportamento quando default avança. Melhor exigir. Cabeçalhos precisam ser documentados em OpenAPI. Ferramentas de geração podem lidar de forma desigual.
QUERY
Versão em query string
Chamadas como `/devices?api-version=2026-07-01` são usadas por Azure e outras plataformas. A versão fica explícita e simples de testar. Gateways podem rotear por parâmetro. URLs, caches e assinaturas precisam incluir. Alguns sistemas removem parâmetros desconhecidos. O cliente deve preservar. A versão não é um filtro de recurso; é contexto do contrato. Logs precisam registrar. Parâmetros obrigatórios em todas as chamadas podem ser verbosos. SDKs encapsulam. O modelo é adequado quando a organização padroniza. Misturar path, query e header dentro da mesma API confunde e aumenta suporte.
COMPAT
Evolução compatível sem nova versão
Adicionar campo opcional, novo endpoint, novo evento ou enum extensível pode ser compatível se clientes ignoram desconhecidos. O contrato deve ser projetado. JSON permite campos novos, mas clientes com desserialização estrita podem quebrar. Enums são problemáticos: um valor novo não deveria causar exceção. Protocol Buffers reserva números e ignora campos desconhecidos. OpenAPI e testes de breaking change ajudam. Versionar tudo gera fragmentação. Não versionar nada transfere risco ao cliente. A regra é avaliar comportamento. Uma unidade de temperatura mudando de °C para °F é breaking mesmo se o tipo continua número.
✅ Vantagens Arquiteturais
⚡
Permite migração gradual de clientes instalados
Aplicativos móveis, hubs e integrações comunitárias não atualizam ao mesmo tempo. Uma versão antiga pode continuar por 6, 12 ou 24 meses enquanto a nova é adotada. A janela deve ser anunciada. Telemetria mostra uso por versão. A equipe contata consumidores. Uma versão sem tráfego pode ser retirada. O custo é infraestrutura, correções e testes duplicados. Vulnerabilidades podem exigir prazo menor. A política precisa equilibrar. Em casa inteligente, um hub embutido pode permanecer anos. APIs locais precisam de compatibilidade longa ou estratégia de firmware. O versionamento formal evita quebra silenciosa após update de nuvem.
⚡
Isola mudanças incompatíveis e simplifica contrato
Em vez de acumular flags como `legacy=true`, v2 pode remover decisões antigas. Isso melhora arquitetura. O backend pode compartilhar domínio e usar presenters diferentes. O risco é manter duas lógicas divergentes. Mudanças de negócio precisam ser aplicadas a ambas quando relevantes. Testes de contrato verificam. A documentação precisa mostrar diferenças e guia de migração. Uma versão nova não é desculpa para reescrever sem necessidade. O impacto em automações, IDs e webhooks deve ser analisado. Webhooks também têm versão de payload, separada da API de gestão.
⚡
Facilita governança em API Gateway e portais
Azure API Management agrupa versões relacionadas e permite scheme por path, header ou query. Produtos e documentação podem publicar. Gateways roteiam. Analytics mostra. Isso centraliza. A configuração precisa de infraestrutura como código. Criar uma versão manualmente e esquecer políticas de autenticação expõe. O version set não garante que backends sejam compatíveis. Quotas, certificados e CORS precisam de paridade. A publicação deve passar por checklist. O gateway ajuda a entregar, não decide semântica.
⚡
Oferece um contrato claro para SDKs e integrações
SDKs podem gerar clientes v1 e v2. OpenAPI recebe documentos separados ou servidores. O código do consumidor fixa. Atualizações tornam mudanças explícitas. A versão da API não é a versão do SDK: SDK 3.4 pode consumir API v2. A matriz deve ser documentada. Pacotes seguem SemVer, mas o serviço possui ciclo. Um cliente deve enviar user-agent e versão para suporte. A clareza reduz diagnóstico. Quando uma integração falha, sabe-se qual contrato. O servidor deve retornar erro informativo para versão removida, como 410 ou mensagem, não 404 genérico.
⚡
Cria processo de depreciação mensurável
Uma API madura define lançamento, suporte, depreciação e sunset. Headers `Deprecation` e `Sunset` podem informar conforme padrões e práticas. Documentação e portal alertam. Logs mostram clientes. A equipe fornece equivalências. O prazo precisa de data absoluta. “Em breve” não é política. Depois, a versão é retirada. O custo de manter versões sem fim é alto e aumenta superfície. O benefício de versionar depende de encerrar com governança. Em integração residencial, avisos devem chegar ao usuário e ao mantenedor, porque uma automação pode parar sem interação diária.