Contratos e compatibilidade
Um contrato regista a estrutura que uma operação de API promete. O Echo reúne o método, o caminho, o documento e as versões publicadas. Um mock pode gerar dados a partir de um contrato e uma aplicação pode associar-se a uma versão para declarar uma dependência. Publicar um contrato não implementa nem testa uma API em execução.
Cria e publica
Abre Contratos no Maestro, cria o contrato e abre Publicar versão. Cola um documento de contrato Echo e revê-o antes de publicar. Este campo espera JSON de um documento Echo, não uma resposta de exemplo nem um JSON Schema por converter. A conversão de esquemas está disponível no editor de rotas de mocks.
As versões publicadas são retratos numerados. A associação de uma aplicação regista a versão acordada. O diff na web mostra caminhos alterados, motivos e veredictos separados para consumidores e fornecedores. Reutilizar conteúdo já publicado pode devolver uma versão anterior existente em vez de criar outra.
Lê a direção certa
A associação Consumes indica que a aplicação chama a operação. Provides indica que a fornece. A comparação distingue alterações de pedido e de resposta e avalia cada lado.
| Alteração | Consumidor | Fornecedor |
|---|---|---|
| Adicionar campo opcional ao pedido | Seguro | Seguro |
| Adicionar campo obrigatório ao pedido | Incompatível | Incompatível |
| Adicionar campo obrigatório à resposta | Seguro | Incompatível |
| Remover campo da resposta ou alterar o tipo | Incompatível | Incompatível |
| Adicionar campo opcional à resposta | Condicional | Seguro |
Estes são os veredictos do classificador atual. Um campo opcional extra na resposta é condicional porque JsonUnmappedMemberHandling.Disallow rejeita campos desconhecidos. Lê a condição e o motivo no diff. Safe significa que não foi encontrada incompatibilidade para esse lado; Warning pede revisão; Breaking identifica incompatibilidade; ConditionalBreaking depende da condição indicada. Um veredicto desconhecido não é aprovação.
Revê antes de aceitar
Um fornecedor pode publicar através de EchoContractPublicationClient, do Gapfy.Echo.Contracts. Cria primeiro o contrato e a associação Provides, depois usa uma chave com PublishOwnedContracts. O cliente publica uma versão de um contrato próprio; não cria contratos nem assume propriedade.
A publicação termina antes de devolver os resultados de compatibilidade. Um veredicto incompatível não anula a publicação. Revê as diferenças antes de alterar um consumidor ou aceitar uma nova referência.
O Gapfy.Echo.Testing compara contratos consumidos com retratos revistos no teu repositório. Pode fazer falhar o CI quando uma mudança quebra esse consumidor. Não testa a API em execução nem valida os contratos que a aplicação fornece.
Próximos passos
Liga a tua aplicação com aplicações e chaves ou usa o documento para servir mocks remotos.