Entendendo API e JSON no Vonage AI Studio com exemplos de hambúrgueres

Noções básicas sobre grelhados

Neste blog, vamos simplificar os conceitos de objetos JSON, respostas de API e mapeamento de respostas no Vonage AI Studio. Abordaremos esses tópicos com exemplos simples e fáceis de entender sobre hambúrgueres (inspirados em Bob’s Burgers). Seja você um desenvolvedor experiente ou um novato em integrações de API, este guia oferecerá informações valiosas para aproveitar ao máximo os recursos do Vonage AI Studio. Como diria Linda Belcher: “A verdadeira tragédia é que não tenho tempo para comer nachos antes de começarmos.” Vamos lá!

Como usar webhooks com o Vonage AI Studio

Os webhooks são essenciais em aplicativos web modernos, servindo como um canal para a transmissão de dados em tempo real. No Vonage AI Studio, o nó de webhooks desempenha um papel fundamental, possibilitando interações com serviços externos e APIs. No AI Studio, os webhooks atuam como ouvintes de eventos provenientes de serviços externos, acionando ações predefinidas em seus fluxos de trabalho. Quando um webhook recebe dados, o recurso de mapeamento de resposta permite que você extraia informações específicas da resposta e as utilize nas etapas subsequentes do seu fluxo de trabalho. Esse recurso é crucial para a criação de aplicativos dinâmicos e responsivos.

Dicas e ferramentas para localizar objetos JSON

Compreender e navegar pelas respostas em JSON (JavaScript Object Notation) é uma habilidade essencial ao trabalhar com APIs REST, incluindo as da Vonage. Como mencionei anteriormente, gosto de trabalhar com JSON devido à sua legibilidade e simplicidade. No entanto, ao lidar com estruturas JSON complexas ou extensas, encontrar os dados exatos de que você precisa pode ser um desafio. Felizmente, existem ferramentas fáceis de usar que simplificam a localização de objetos JSON, mesmo para quem está começando a trabalhar com respostas de API.

O que é um objeto JSON?

Primeiro, vamos entender o que é um objeto JSON. Em sua forma mais simples, um objeto JSON é uma coleção de pares chave-valor entre chaves {}. Cada chave é um identificador único (geralmente uma string), e o valor associado a ela pode ser um número, uma string, um booleano, outro objeto, um array ou nulo. Por exemplo:

{
  "item": "burger",
  "quantity": 2,
  "withFries": true,
  "extras": ["cheese", "lettuce"],
  "specialInstructions": null
}

Neste objeto JSON:

• item (Texto): O item encomendado é um "burger".

• quantity (Número): A quantidade é representada por um número, 2.

• withFries (Booleano): Esta chave indica se a porção de batatas fritas está incluída no pedido (true ou false). Aqui, o valor é true.

• extras (Matriz): Lista os recheios adicionais como uma matriz, incluindo "cheese" e "lettuce".

• specialInstructions (Nulo): Usado para quaisquer instruções adicionais; atualmente não possui valor (null).

Este exemplo apresenta uma representação clara e simples de um pedido de hambúrguer, utilizando diferentes tipos de valores no formato JSON.

Neste exemplo, item, quantity, withFries, extras, e specialInstructions são chaves, e "burger", 2, true, ["cheese", "lettuce"], e null são seus respectivos valores.

Como navegar pelas respostas JSON

1. Entendendo a estrutura do JSON: Comece se familiarizando com a estrutura da resposta JSON. Identifique a hierarquia de objetos e matrizes (listas de valores).

2. Formatação para maior clareza: As respostas JSON das APIs podem, às vezes, ser compactas e difíceis de ler. Use uma ferramenta de formatação para “embelezar” o JSON, tornando-o mais legível. Ferramentas como o JSONLint (jsonlint.com) oferecem essa funcionalidade. Elas pegam uma string JSON compacta e a formatam com recuos e quebras de linha adequadas.

Ferramentas para localizar objetos JSON

1. JSONLint: Como mencionado, o JSONLint é ótimo para formatar JSON. Ele também valida a sintaxe do JSON, ajudando você a detectar e corrigir erros que possam impedir a análise correta.

2. JSONPath Finder: Para estruturas JSON mais complexas, ferramentas como o JSONPath Finder podem ser de grande utilidade. Essas ferramentas permitem que você consulte e extraia partes específicas do JSON. Você insere um “caminho” usando uma linguagem de consulta semelhante ao XPath para XML, e a ferramenta retorna a parte do JSON que corresponde à sua consulta.

Usando o exemplo acima de pedidos, imagine que quiséssemos saber quantos pedidos vendemos com batatas fritas hoje. $.orders[*].withFries. Da mesma forma, em uma resposta JSON da Vonage que inclua uma lista de registros de chamadas, talvez você queira extrair o ID do chamador de cada registro. Com uma consulta JSONPath como $.calls[*].callerID, você pode obter rapidamente todos os IDs de chamadas da lista.

Como entender as respostas da API REST

REST API significa “Interface de Programação de Aplicativos para Transferência de Estado Representacional”.

• Transferência de Estado Representacional (REST) é um estilo arquitetônico para o projeto de aplicativos em rede. Ele se baseia em um protocolo de comunicação cliente-servidor sem estado, quase sempre o HTTP (Protocolo de Transferência de Hipertexto).

• Interface de Programação de Aplicativos (API) é um conjunto de regras e definições que permite que diferentes aplicações de software se comuniquem entre si.

No contexto dos serviços web, uma API REST oferece uma maneira de as aplicações interagirem com serviços web utilizando os protocolos da web (como o HTTP) e, normalmente, envolve a solicitação e a transferência de dados por meio de operações como GET, POST, PUT e DELETE. As APIs REST são amplamente utilizadas devido à sua simplicidade, escalabilidade e versatilidade. É isso que as torna a espinha dorsal da comunicação na web, e compreender suas respostas é fundamental para uma integração bem-sucedida.

As respostas da API geralmente vêm no formato JSON. Como sou uma pessoa que gosta de visualizações, eu simplesmente adoro o quanto a estrutura JSON é leve e legível quando é apresentada de forma mais agradável. Vamos explorar as nuances das respostas da API REST, enfatizando o papel do formato JSON em garantir uma troca eficiente de dados e a integração com o Vonage AI Studio.

Criação de um caminho de objeto

Ao trabalhar com respostas JSON de APIs, especialmente em ferramentas como o Vonage AI Studio, uma das habilidades mais importantes é compreender e criar “caminhos de objetos”.

O que é um caminho de objeto?

Um caminho de objeto é uma sequência de chaves que você segue para navegar por um objeto JSON e chegar aos dados específicos que deseja. Pense no caminho de objeto como uma rota de GPS que o leva à informação exata de que você precisa dentro de uma estrutura JSON. Por exemplo, em um objeto JSON que representa uma pessoa, o caminho de objeto para encontrar o e-mail dela pode ser algo como person.contact.email.

Como construir um caminho de objeto

1. Comece pela raiz: A raiz de um objeto JSON é seu nível mais externo. A partir daí, você identifica a primeira chave que o leva mais perto dos seus dados.

2. Navegar pelas camadas: Se o valor de uma chave for outro objeto ou uma matriz, continue especificando a próxima chave ou o próximo índice da matriz.

3. Repita até chegar aos dados desejados: Continue especificando chaves ou índices até chegar aos dados de que precisa.

Exemplo prático no Vonage AI Studio

Vamos usar uma resposta JSON simples para ilustrar como construir um caminho de objeto. Imagine que você tenha a seguinte resposta JSON de uma API da Vonage:

{
  "order": {
    "details": {
      "item": "burger",
      "size": "large",
      "customizations": {
        "extras": ["cheese", "lettuce", "tomato"],
        "exclude": ["pickles"],
        "sauces": ["ketchup", "mustard"]
      }
    },
    "customerInfo": {
      "name": "Bob",
      "contact": {
        "email": "bob@bobsburgers.com",
        "phone": "555-6789"
      }
    }
  }
}

• Objetivo: Digamos que queremos extrair o(s) item(ns) excluído(s) do pedido de hambúrguer.

• Construindo o caminho estendido do objeto:

  1. Comece pela raiz: A chave raiz é order.

  2. Primeira camada: No interior order, navegamos até details.

  3. Segunda camada: Dentro details, encontramos customizations.

  4. Destino final: O customizations objeto contém a chave exclude.

• Caminho final do objeto: O caminho do objeto para localizar a lista de molhos é order.details.customizations.exclude.

Como usar caminhos de objetos no Vonage AI Studio

No AI Studio, ao definir mapeamentos de resposta ou configurar nós no nó webhook, muitas vezes você precisará especificar esses caminhos de objeto para indicar ao Studio exatamente onde localizar e extrair os dados necessários de uma resposta de API. Os caminhos dos objetos são essenciais porque permitem identificar e extrair apenas os dados necessários de estruturas JSON potencialmente complexas, tornando o manuseio de dados eficiente e livre de erros.

Como passar/adicionar parâmetros de consulta às solicitações de API

Nesta seção, vamos explorar como a definição de parâmetros nas interações com APIs é semelhante à personalização do seu pedido de comida. Assim como você pode especificar como deseja seu hambúrguer em um restaurante, os parâmetros em uma solicitação de API permitem que você defina exatamente quais dados precisa. Usaremos uma analogia simples com o pedido de um hambúrguer para explicar esse conceito, juntamente com um conjunto de dados de exemplo para ilustrar como isso se aplica em um cenário prático.

Exemplo: Um pedido de hambúrguer

Imagine que você está no Bob’s Burgers e quer pedir um hambúrguer. No entanto, você não gosta de picles. Então, você diz ao garçom: “Gostaria de um cheeseburger, mas sem picles, por favor”. Nesse caso, “sem picles” é um pedido especial ou parâmetro que personaliza o seu pedido.

O que são parâmetros de consulta?

• Analogia com a vida real: Os parâmetros de consulta são como suas preferências ao fazer um pedido de comida. Quando você pede algo específico, como um hambúrguer sem picles, está definindo parâmetros para o seu pedido.

• Em termos de API: Parâmetros são os valores que você envia junto com sua solicitação de API. Eles determinam quais informações você deseja obter da API. Por exemplo, se você estiver solicitando informações sobre um usuário, um parâmetro pode ser o ID do usuário. Eles permitem que você personalize sua solicitação de dados. Usar parâmetros significa que você obtém exatamente e apenas o que precisa de uma API.

Conversão para parâmetros de API

• Solicitação de API: No mundo das APIs, uma solicitação é como seu pedido para a cozinha. Os detalhes que você fornece (como “sem picles”) são parâmetros que personalizam essa solicitação.

• Definição de parâmetros: Ao especificar determinados detalhes em sua solicitação de API, você está definindo parâmetros. Esses parâmetros informam à API exatamente como “preparar” seus dados.

Configurando parâmetros no Vonage AI Studio

1. Identifique suas necessidades de dados: Entenda quais informações específicas você precisa da API e quais informações ela é capaz de fornecer. Por exemplo, se você pedir uma pizza no Bob’s Burgers, a cozinha vai retornar um erro, pois esse não é um parâmetro de consulta que ela saiba como processar.

2. Use a interface do Vonage AI Studio: O Studio oferece uma maneira intuitiva de definir parâmetros. Por exemplo, se você estiver obtendo dados do usuário, poderá definir um parâmetro para o “userID”.

3. Insira os valores dos parâmetros: Esses valores devem corresponder aos dados que você está tentando recuperar. No nosso exemplo, seria o ID real do usuário.

Dados de exemplo para solicitação de API

Vamos criar um conjunto de dados de exemplo para visualizar isso:

{
  "order": {
    "item": "burger",
    "extras": ["cheese", "lettuce", "tomato"],
    "exclude": []
  }
}

Exemplo prático: como personalizar seu pedido no Vonage AI Studio

1. Pedido inicial: Usando os dados de exemplo, seu pedido inicial é um hambúrguer com queijo, alface e tomate.

2. Definição de parâmetros para personalização: Suponha que você não queira picles no seu hambúrguer. Em uma configuração de API, como o Vonage AI Studio, você adicionaria “picles” ao parâmetro “excluir”.

3. Dados da ordem modificados:

   {
     "order": {
       "item": "burger",
       "extras": ["cheese", "lettuce", "tomato"],
       "exclude": ["pickles"]
     }
   }

   Copiar

4. Resultado: A API processa essa solicitação e retorna uma resposta que reflete seu pedido personalizado – um hambúrguer com queijo, alface e tomate, mas sem picles.

Veja como ficaria em uma tabela de banco de dados:

Inscreva-se na “Lista de Convidados” do Burger da Vonage

Neste artigo, aprendemos o básico sobre como lidar com objetos JSON, respostas de API e mapeamento de respostas no Vonage AI Studio, tudo por meio de exemplos fáceis de entender, inspirados na série “Bob’s Burgers”. Se você gostou do que leu, junte-se à nossa “lanchonete” de desenvolvedores no Slack e siga a gente no X, antes conhecido como Twitter. Se você achou este blog útil de alguma forma, compartilhe sua avaliação e me marque — adoraria saber como foi a sua “experiência gastronômica”!