Contratos e compatibilidade
Um contrato registra 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 se vincular a uma versão para declarar uma dependência. Publicar um contrato não implementa nem testa uma API em execução.
Crie e publique
Abra Contratos no Maestro, crie o contrato e abra Publicar versão. Cole um documento de contrato Echo e revise antes de publicar. Esse campo espera JSON de um documento Echo, não uma resposta de exemplo nem um JSON Schema sem conversão. A conversão de esquemas está disponível no editor de rotas de mocks.
As versões publicadas são retratos numerados. O vínculo de uma aplicação registra a versão acordada. O diff na web mostra caminhos alterados, motivos e avaliações separadas para consumidores e fornecedores. Reutilizar conteúdo já publicado pode devolver uma versão anterior existente em vez de criar outra.
Leia a direção certa
O vínculo Consumes indica que a aplicação chama a operação. Provides indica que ela fornece a operação. A comparação distingue alterações de requisição e de resposta e avalia cada lado.
| Alteração | Consumidor | Fornecedor |
|---|---|---|
| Adicionar campo opcional à requisição | Seguro | Seguro |
| Adicionar campo obrigatório à requisição | 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 |
Essas são as avaliações do classificador atual. Um campo opcional extra na resposta é condicional porque JsonUnmappedMemberHandling.Disallow rejeita campos desconhecidos. Leia a condição e o motivo no diff. Safe significa que não foi encontrada incompatibilidade para aquele lado; Warning pede revisão; Breaking identifica incompatibilidade; ConditionalBreaking depende da condição indicada. Uma avaliação desconhecida não é aprovação.
Revise antes de aceitar
Um fornecedor pode publicar por EchoContractPublicationClient, do Gapfy.Echo.Contracts. Primeiro crie o contrato e o vínculo Provides, depois use 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. Uma avaliação incompatível não desfaz a publicação. Revise as diferenças antes de alterar um consumidor ou aceitar uma nova referência.
O Gapfy.Echo.Testing compara contratos consumidos com retratos revisados no seu repositório. Pode fazer o CI falhar 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
Conecte sua aplicação com aplicações e chaves ou use o documento para servir mocks remotos.