Testar a interface da API REST do Couchbase Sync Gateway usando o Postman

O Gateway de sincronização do Couchbase é um dos principais componentes da pilha do Couchbase Mobile. Em um alto nível, ele é responsável pelo roteamento e sincronização seguros dos dados entre os clientes da Web e móveis e o servidor Couchbase. Ele oferece suporte a uma API REST que permite que os clientes executem administrador e não-administrador operações no banco de dados do Couchbase Server. Se você estiver desenvolvendo um aplicativo cliente que faça interface com o Sync Gateway, precisará de uma maneira conveniente de explorar a API e testá-la, provavelmente até mesmo simulando todas as chamadas para o Sync Gateway. Podemos usar o Postman para essa finalidade.

Carteiro é uma ferramenta de teste, desenvolvimento e documentação de API. O Sync Gateway oferece suporte a coleções Postman correspondentes à interface REST pública e de administração. Em uma versão anterior do postagemEm nosso artigo sobre o Postman, abordamos os princípios básicos de como começar a usar o Postman para testes da API do Sync Gateway. Desde então, houve melhorias substanciais nas coleções do Postman do Sync Gateway e, é claro, houve mudanças no próprio Postman. Esta postagem discute os aprimoramentos das definições de coleção. A postagem também inclui uma demonstração em vídeo.

Tudo o que foi discutido nesta postagem usa a versão comunitária gratuita da ferramenta Postman.

Histórico

A pilha do Couchbase Mobile inclui o Couchbase Server, o Couchbase Sync Gateway e o banco de dados incorporado Couchbase Lite. Esta publicação pressupõe que você esteja familiarizado com a pilha do Couchbase Mobile. Se quiser ler mais sobre o Couchbase, você pode consultar o recursos em nosso site do Couchbase.
A postagem também pressupõe que você tenha um conhecimento básico do uso do Postman. Se você quiser se atualizar, consulte este fora.

TL;DR

Se preferir, você pode assistir ao vídeo abaixo, que é uma demonstração de tudo o que foi discutido nesta postagem do blog.

Instalação do Postman

Antes de continuar, você deve fazer o download e instalar o Ferramenta Postman. Você também precisará criar uma conta gratuita.

Importando a coleção Postman do Sync Gateway

Começar a usar o Postman com o Sync Gateway é muito fácil.

• Primeiro, faça o download das coleções postman do Sync Gateway no repositório do GitHub

• Siga as instruções detalhadas nesta seção postagem introdutória para importar as coleções e os arquivos de ambiente para o Postman. No final, sua configuração deverá ser semelhante a esta.
  

Execução de solicitações simuladas

Você pode testar a API do Sync Gateway com o Postman mesmo sem ter um Sync Gateway em execução no seu ambiente. Observe que o Postman impõe limites ao número de chamadas simuladas que você pode fazer usando a conta gratuita. Portanto, se você planeja usar isso extensivamente, talvez seja necessário usar a versão Pro da ferramenta.

Criar um gateway de sincronização simulado

• Siga as instruções aqui para adicionar um servidor simulado. É literalmente um clique de um botão para criar um servidor simulado
  
• Examine as variáveis de ambiente do Sync Gateway Postman. A variável "adminurl" aponta para o ponto de extremidade do URL do administrador e o ponto de extremidade "publicurl" aponta para o ponto de extremidade do URL público. Atualize essas variáveis para apontar para o servidor de simulação recém-criado
  
• É isso aí! Você está pronto para executar sua solicitação em seu servidor de simulação

Um exemplo é a execução de uma solicitação com o Postman em um servidor de gateway de sincronização simulado

Como são geradas as respostas simuladas do Postman e como o Postman armazena as respostas em cache?

A coleção Sync Gateway vem com respostas pré-construídas que você pode localizar na pasta "examples". Essa resposta é retornada quando você faz o teste com o servidor de simulação. Você pode usar as respostas de amostra na pasta "examples" como referência, mesmo sem executar as solicitações.

Testes de carteiro

Cada solicitação tem um script de teste associado. Os testes são bastante simples e, em sua maioria, verificam o código de status HTTP. Você pode estender esses testes para fazer um processamento mais abrangente da resposta.

Teste com uma instância do Sync Gateway

Embora os testes de simulação sejam ótimos para a exploração da API e durante o desenvolvimento inicial, eles não são equivalentes aos testes com o sistema real!

• Se ainda não tiver feito isso, faça o download da instância do Sync Gateway e/ou do Couchbase Server
  • Siga as instruções aqui para fazer download e instalar o Sync Gateway. Se você quiser manter seus dados no Couchbase Server, siga as instruções neste Início rápido guia para instalar o Couchbase Server.
  • Se preferir usar o Docker, você pode seguir as instruções aqui para começar a usar o Couchbase Mobile usando o Docker.
• Há uma amostra arquivo sync-gateway-config que está disponível no mesmo repositório do Collections GitHub que você obteve anteriormente. Os valores de configuração especificados no arquivo de configuração de amostra correspondem às variáveis de ambiente padrão. Portanto, se você quiser usar os valores padrão no arquivo de ambiente, poderá iniciar o gateway de sincronização com a amostra arquivo sync-gateway-config.
• Atualize o "adminurl" e "publicurl" para apontar para os pontos de extremidade público e administrativo de sua implementação de gateway de sincronização.
• Se você iniciou o Sync Gateway com um arquivo de configuração diferente do arquivo amostra de sync-gateway-config então, além de atualizar o arquivo "adminurl" e "publicurl", certifique-se de atualizar as outras variáveis de ambiente relevantes para que correspondam à sua configuração. Algumas delas incluem "db", "name" (nome), "senha" e "doc"

É isso, você está pronto para testar em um sistema ativo!

Encadeamento de solicitações

Uma das coisas interessantes que suportamos em nossas coleções é o encadeamento de solicitações, ou seja, a saída de uma solicitação pode ser usada como entrada para uma solicitação subsequente. Isso é feito por meio da atualização dinâmica das variáveis de ambiente com os resultados da execução da solicitação, sem a necessidade de editar manualmente as solicitações.

Por exemplo,
- Quando você cria um documento, uma nova revisão do documento é criada e o revisionID da revisão recém-criada é retornado na resposta no campo "_rev" campo. Temos um teste que extrai o campo "_rev" e define a variável de ambiente "rev".

• A solicitação subsequente para atualizar o documento exige que o revisionID seja especificado na solicitação. Isso é recuperado da variável de ambiente "rev" que foi preenchida como resultado da solicitação de execução anterior.

Snippets de código do cliente Postman

Outro recurso útil no uso do cliente Postman é o "Code snippet generator" (Gerador de trechos de código). Você pode gerar trechos de código correspondentes às solicitações em uma das muitas linguagens suportadas

Gerador de documentação do Postman

A documentação da API em nosso Portal do desenvolvedor do Couchbase deve ser considerada a fonte da verdade.

No entanto, se você quiser visualizar uma "versão da Web" da documentação gerada pelo Postman correspondente à sua coleção. Você pode fazer isso selecionando a opção "view in web". Observe que seu cliente local do Postman deve estar "sincronizado" com sua conta on-line do Postman.

A documentação gerada seria semelhante a esta. Você precisaria de uma conta no Postman para poder visualizar a documentação.

Próximas etapas

Se você encontrar um problema nas definições das coleções ou se quiser aprimorá-las com testes adicionais, envie uma solicitação pull para o Github Repo.

Se tiver dúvidas ou comentários, deixe um comentário abaixo ou entre em contato comigo pelo Twitter @rajagp ou envie-me um e-mail priya.rajagopal@couchbase.com. O Fóruns do Couchbase são outro bom lugar para entrar em contato com perguntas.