AsyncAPI

O documento modela os locais pelos quais as mensagens circulam. Em MQTT, um channel pode corresponder a um tópico como casa/sala/temperatura; em Kafka, a um topic; em AMQP, a uma fila, exchange ou endereço conforme o binding. O endereço pode conter parâmetros, como casa/{id}/estado, e deve declarar o significado de cada variável. A especificação separa a identidade lógica do canal da sintaxe concreta do protocolo. Isso ajuda a manter um contrato único, mas não elimina diferenças de roteamento. Wildcards de MQTT, partições Kafka e exchanges AMQP possuem comportamentos próprios e precisam ser expressos nos bindings ou na documentação. Um erro frequente é usar o channel apenas como string e deixar retenção, partição, ordenação e política de acesso fora do contrato. Em automação residencial, o canal deve indicar domínio, entidade, direção, unidade e versão do payload sem expor credenciais.

AsyncAPI 3.x representa ações de send e receive de forma explícita e associa cada operação aos canais utilizados. A perspectiva é a da aplicação descrita: send significa que ela envia mensagens; receive, que consome. Essa direção precisa ser clara para evitar documentação invertida. Uma integração de gateway Zigbee pode receber comandos no canal casa/luz/set e enviar estados em casa/luz/state. As operações podem ter título, resumo, segurança, traits e mensagens. A modelagem permite gerar stubs e testes, mas o runtime continua responsabilidade do código. A declaração não garante idempotência, entrega ou ordenação. Esses aspectos devem aparecer nos bindings, cabeçalhos e requisitos. Operações também precisam registrar respostas assíncronas por correlationId quando o fluxo exige confirmação, em vez de presumir que publicar equivale a executar fisicamente.

Cada mensagem pode declarar headers, payload, contentType, exemplos, correlationId e schema. JSON Schema é comum, mas a especificação aceita outros formatos e referencia documentos externos. O contrato deve distinguir o envelope do domínio. Um payload de telemetria pode conter value, unit, timestamp, quality e sequence. A unidade precisa ser fixa ou enumerada. O timestamp deve indicar UTC e formato. O schema valida estrutura, não plausibilidade física; um valor de 900 °C pode ser válido sintaticamente se não houver limite. Limites, enums e padrões devem ser adicionados quando estáveis. Exemplos precisam representar casos normais e erros. Em sistemas de automação, a mensagem deve incluir versão ou ser compatível por evolução. Alterar o tipo de number para string quebra consumidores mesmo que o broker continue aceitando bytes.

Bindings acrescentam detalhes específicos de MQTT, Kafka, AMQP, WebSocket, HTTP e outros. Em MQTT, podem registrar QoS, retain e informações de sessão; em Kafka, grupos, chaves e schema registry; em AMQP, propriedades de fila e exchange. O binding evita reduzir todos os transportes ao mesmo denominador. Entretanto, a cobertura depende da versão do binding e da ferramenta. Uma opção suportada pelo broker pode não estar modelada. O contrato deve declarar versões de binding e extensões. Se a integração usa MQTT 5 com response topic, correlation data ou user properties, esses detalhes precisam ser documentados. Não se deve afirmar portabilidade automática para AMQP apenas porque ambos usam publish/subscribe; semântica de roteamento, confirmação e retenção diverge.

A seção servers descreve endpoints, protocolo, versão, variáveis de ambiente e mecanismos de segurança. Pode haver produção, homologação e rede local. URLs e nomes não devem conter segredos. Segurança referencia schemes como user/password, API key, X.509, OAuth 2.0 ou SASL, conforme o transporte. O documento precisa separar autenticação de autorização. TLS protege o canal, mas ACLs definem tópicos. Para uma casa inteligente, um broker local pode usar mqtts://broker.local:8883 e um serviço gerenciado outro endpoint. Certificados, CA e rotação ficam na operação, não no arquivo público. A existência do server no contrato não prova disponibilidade. Health checks e monitoramento são complementares.