Como usar variáveis e encadear solicitações no Postman

Na Vonage, utilizamos o OpenAPI para descrever todas as nossas APIs e também disponibilizamos essas especificações publicamente disponíveis. Uma das coisas que mais gostamos de fazer com um arquivo OpenAPI que ainda não conhecemos é importá-lo para o Postman. Por isso, decidimos retribuir o favor e criar uma Coleção do Postman para nossas APIs, de modo que avaliá-las e explorá-las seja mais rápido e fácil do que nunca.

Neste artigo, mostramos como você pode tornar a exploração de suas APIs no Postman ainda mais acessível. Usaremos a coleção de APIs da Vonage no Postman como exemplo; portanto, certifique-se de verificar a lista de pré-requisitos caso queira acompanhar o passo a passo.

Pré-requisitos

• Postman Account

As variáveis são suas aliadas

Ao importar pela primeira vez a Coleção de APIs da Vonage para o Postman, você verá uma pasta “Vonage APIs” surgir em Coleções , no lado esquerdo da tela.

Você também pode notar as “36 solicitações” abaixo do nome da coleção. Dependendo do tipo de autenticação, isso significa que, mais ou menos, 36 vezes alguém teria que adicionar api_key e api_secret como parâmetros de solicitação.

Felizmente, o Postman oferece suporte a variáveis de ambiente, globais e de coleção, o que tornará a experiência muito mais tranquila e menos trabalhosa. Em vez de realizar tarefas repetitivas, como preencher os mesmos valores de parâmetros em cada solicitação, essas variáveis nos permitem obter esses valores dinamicamente.

Nossa coleção vem com um Ambiente Vonage , onde você pode fornecer sua chave e seu segredo; a partir daí, todas as solicitações usarão esses valores.

Dessa forma, fazer uma solicitação simples, como verificar o saldo da sua Account com a API de Account torna-se uma tarefa que pode ser feita com um único clique.

Algumas outras solicitações podem exigir parâmetros adicionais. Por exemplo, para enviar um SMS, você precisaria preencher to, from e text no corpo da solicitação, mas api_key e api_secret ainda seria preenchido automaticamente. Você também pode optar por adicionar qualquer um desses parâmetros como variáveis, como o to número foi salvo como uma variável de coleção na solicitação apresentada abaixo. Você pode fazer isso editando diretamente sua coleção ou ambiente, ou selecionando o valor codificado que deseja substituir por uma variável e clicando em Definir como variável > Definir como nova variável.

Encadeamento de solicitações

As variáveis no Postman são ótimas, mas não são uma ferramenta universal para resolver todos os problemas complicados.
Por exemplo, ao usar uma das APIs da Vonage que se autentica por meio de JWTs, você precisará gerar esse JWT antes de fazer sua solicitação. Para gerar o JWT, você precisará de um ID de aplicativo e de uma chave privada, que você obterá ao criar um aplicativo da Vonage. Isso significa que é preciso fazer três solicitações separadas, o que pode confundir quem está explorando a API pela primeira vez.

Felizmente, também existe uma solução alternativa para pré-requisitos com várias etapas: o encadeamento de solicitações.
O Postman oferece duas áreas de script: Script de Pré-Solicitação e Testes, onde você pode escrever qualquer código JavaScript que desejar — sim, incluindo a realização de outra solicitação HTTP também.

O script de pré-solicitação

A Voice API da Vonage realiza a autenticação por meio de JSON Web Tokens (JWTs); portanto, para enviar uma criar uma solicitação de chamada de saída , primeiro precisaríamos:

1. Criar um aplicativo Vonage usando a API de aplicativos

2. Pegue o application_id e private_key do objeto de resposta e use-os para gerar um JWT.

// Check if we already have a JSON Web Token, continue if not
if (!pm.environment.has("JWT")) {
    var btoa = require('btoa')
    let base64keyandsecret = btoa(`${pm.environment.get("api_key")}:${pm.environment.get("api_secret")}`)

// (1) Create a Voice Application by making a request to the Vonage Applications API
    pm.sendRequest({
        url: 'https://api.nexmo.com/v2/applications',
        method: 'POST',
        header: [`Authorization:Basic ${base64keyandsecret}`, "Content-Type: application/json"],
        body: JSON.stringify({
            "name": "Demo Postman Application",
            "capabilities": {
                "voice": {
                    "webhooks": {
                        "answer_url": {
                            "address": "https://example.com/webhooks/answer",
                            "http_method": "POST"
                        },
                        "event_url": {
                            "address": "https://example.com/webhooks/event",
                            "http_method": "POST"
                        }
                    }
                }
            }
        })
    }, (err, res) => {
// (2) Generate JWT using the application ID as a claim and sign it with the private key
        pm.sendRequest({
            url: 'https://jwtapi-dev.netlify.app/.netlify/functions/generate',
            method: 'POST',
            header: ["Content-Type: application/json"],
            body: JSON.stringify({
                algorithm: "RS256",
                private_key: res.json().keys.private_key,
                claims: {
                    application_id: res.json().id,
                    exp: parseInt((Date.now() / 1000) + 3600, 10)
                }
            })
        }, (err, res) => {
            pm.environment.set("JWT", res.json().signed_jwt)
        })
    })
}

Testes: Por que não usar um script pós-solicitação?

O Postman permite que você adicione testes a solicitações individuais, pastas e coleções. Embora esses testes sejam extremamente úteis para garantir que sua API esteja funcionando conforme o esperado e para fins de depuração, há um porém: os testes são scripts em JavaScript que são executados após a solicitação ter sido feita. Isso significa que a maneira como usamos o Script Pré-Solicitação, poderíamos aproveitar ao máximo o área de também.

No nosso exemplo de chamada de voz, ao concluir com sucesso, estou salvando a voice_call_uuid como uma variável de coleção usando a pm.collectionVariables.set() função. Essa variável será útil caso eu decida fazer outras solicitações envolvendo a Voice API. Por outro lado, em caso de falha, estou zerando o JWT valor usando a pm.environment.unset("JWT") expressão, para que eu possa enviar minha solicitação novamente e gerar um novo JWT.

if (pm.response.code == "201") {
    pm.collectionVariables.set("voice_call_uuid", pm.response.json().uuid);
} else {
    pm.environment.unset("JWT")
}

Saiba mais sobre como definir variáveis em scripts na documentação do Postman.

O corpo da solicitação

Por fim, vamos juntar tudo isso para fazer uma chamada de voz com conversão de texto em fala. Você pode usar o trecho de código abaixo e fornecer o to e from como variáveis ou valores fixos. Lembre-se de que to é o número de destino para o qual você está prestes a ligar, e from é um dos seus números da Vonage. Obtenha um no seu painel , caso ainda não tenha feito isso.

O NCCO é nosso Objeto de Controle de Chamada, que lista todas as ações a serem realizadas assim que a chamada for atendida. Confira a Referência do NCCO e veja quais outras ações você pode incluir no seu fluxo de chamadas.

{
    "to": [
        {
            "number": {{to}},
            "type": "phone"
        }
    ],
    "from": {
        "number": {{from}},
        "type": "phone"
    },
    "ncco": [
        {
          "action": "talk",
          "text": "This is a text to speech call from Vonage"
        }
      ]
}

Essa solicitação já está pronta, então envie essa Enviar . Parabéns! E sabe qual é a melhor parte de tudo isso? Se você salvar suas alterações e Compartilhar coleção, a próxima pessoa só precisará preencher os valores das variáveis que faltam e clicar no botão Enviar .

Como você usaria esses recursos úteis do Postman? Tem alguma dica ou truque? Conte para a gente; estamos ansiosos para ver o que você vai criar!

E agora, para onde vamos?

• Apresentamos a coleção de APIs da Vonage no Postman

• Coleção do Postman para APIs da Vonage

• Guia sobre o uso de variáveis

• Referência da API de Account

• Referência da SMS API

• Referência da Voice API NCCO