Comprender API y JSON en Vonage AI Studio con ejemplos de Burger

Asar a la parrilla: lo básico

En este blog, simplificaremos los conceptos de objetos JSON, respuestas de API y asignación de respuestas en Vonage AI Studio. Cubriremos estos temas con ejemplos de hamburguesas sencillos y relacionados (inspirados en Hamburguesas de Bob). Tanto si eres un desarrollador experimentado como si eres nuevo en las integraciones de API, esta guía te brindará información valiosa para aprovechar al máximo las capacidades de Vonage AI Studio. Como diría Linda Belcher: "La verdadera tragedia es que no tengo tiempo para comer nachos antes de comenzar". ¡Comencemos!

Cómo usar Webhooks con Vonage AI Studio

Los webhooks son vitales en las aplicaciones web modernas, ya que sirven como canal para la transmisión de datos en tiempo real. En Vonage AI Studio, el nodo nodo webhooks desempeña un papel fundamental, ya que permite interactuar con servicios externos y API. En AI Studio, los webhooks actúan como oyentes de eventos de servicios externos, desencadenando acciones predefinidas dentro de tus flujos de trabajo. Cuando un webhook recibe datos, la función de asignación de respuestas permite extraer información específica de la respuesta y utilizarla en pasos posteriores del flujo de trabajo. Esta capacidad es crucial para crear aplicaciones dinámicas y con capacidad de respuesta.

Trucos y herramientas para localizar objetos JSON

Comprender y navegar a través de las respuestas JSON (JavaScript Object Notation) es una habilidad fundamental cuando se trabaja con API REST, incluidas las de Vonage. Como mencioné anteriormente, disfruto trabajar con JSON debido a su legibilidad y simplicidad. Sin embargo, cuando se trata de estructuras JSON complejas o grandes, encontrar los datos exactos que necesitas puede ser un desafío. Afortunadamente, existen herramientas fáciles de usar que facilitan la localización de objetos JSON, incluso para aquellos que no están familiarizados con el trabajo con respuestas API.

¿Qué es un objeto JSON?

En primer lugar, entendamos qué es un objeto JSON. En su forma más simple, un objeto JSON es una colección de pares clave-valor encerrados entre llaves {}. Cada clave es un identificador único (normalmente una cadena), y el valor asociado a ella puede ser un número, una cadena, un booleano, otro objeto, una matriz o nulo. Por ejemplo:

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

En este objeto JSON:

• item (Texto): El artículo pedido es un "burger".

• quantity (Numbers): La cantidad se representa como un número, 2.

• withFries (booleana): Esta clave indica si las patatas fritas se incluyen con el pedido (true o false). En este caso, es true.

• extras (Matriz): Lista los toppings adicionales como una matriz, incluyendo "cheese" y "lettuce".

• specialInstructions (Nulo): Se utiliza para cualquier instrucción adicional, actualmente no tiene valor (null).

Este ejemplo proporciona una representación clara y sencilla de un pedido de hamburguesas, utilizando diferentes tipos de valores en formato JSON.

En este ejemplo, item, quantity, withFries, extrasy specialInstructions son claves, y "burger", 2, true, ["cheese", "lettuce"]y null son sus respectivos valores.

Cómo navegar por las respuestas JSON

1. Comprender la estructura de JSON: Empieza por familiarizarte con la estructura de la respuesta JSON. Identifica la jerarquía de objetos y arrays (listas de valores).

2. Formato para mayor claridad: Las respuestas JSON de las API a veces pueden ser compactas y difíciles de leer. Utilice una herramienta herramienta de formateo para "embellecer" el JSON y hacerlo más legible. Herramientas como JSONLint (jsonlint.com) ofrecen esta funcionalidad. Toman una cadena JSON compacta y la formatean con la sangría y los saltos de línea adecuados.

Herramientas para localizar objetos JSON

1. JSONLint: Como ya se ha mencionado, JSONLint es genial para formatear JSON. También valida la sintaxis JSON, ayudando a detectar y corregir errores que podrían impedir el correcto análisis sintáctico.

2. Buscador JSONPath: Para estructuras JSON más complejas, herramientas como JSONPath Finder pueden ser muy valiosas. Estas herramientas permiten consultar y extraer partes específicas de JSON. Se introduce una "ruta" utilizando un lenguaje de consulta similar a XPath para XML, y la herramienta devuelve la parte del JSON que coincide con la consulta.

Utilizando el ejemplo anterior de los pedidos, imaginemos que quisiéramos saber cuántos pedidos hemos vendido hoy con Fries. $.orders[*].withFries. Del mismo modo, en una respuesta JSON de Vonage que incluya una lista de registros de llamadas, es posible que desees extraer el ID de la persona que llama de cada registro. Con una consulta JSONPath como $.calls[*].callerIDpuedes obtener rápidamente todos los identificadores de llamadas de la lista.

Cómo entender las respuestas de la API REST

REST API son las siglas de "Representational State Transfer Application Programming Interface".

• Transferencia de Estado Representacional (REST) es un estilo arquitectónico para diseñar aplicaciones en red. Se basa en un protocolo de comunicación cliente-servidor sin estado, casi siempre HTTP (Hypertext Transfer Protocol).

• Interfaz de programación de aplicaciones (API) es un conjunto de reglas y definiciones que permite a distintas aplicaciones informáticas comunicarse entre sí.

En el contexto de los servicios web, una API REST ofrece a las aplicaciones una forma de interactuar con los servicios web utilizando los protocolos de la web (como HTTP) y suele implicar la solicitud y transferencia de datos mediante operaciones como GET, POST, PUT y DELETE. Las API REST son muy utilizadas por su sencillez, escalabilidad y versatilidad. Eso es lo que las convierte en la columna vertebral de la comunicación web, y entender sus respuestas es clave para una integración exitosa.

Las respuestas de la API suelen venir en formato JSON. Como persona visual, me encanta me encanta lo ligera y legible que es la estructura JSON cuando se hace más bonita. Exploraremos los matices de las respuestas de REST API, enfatizando el rol del formato JSON para garantizar un intercambio de datos eficiente y la integración con Vonage AI Studio.

Creación de una ruta de objetos

Al trabajar con respuestas JSON de API, especialmente en herramientas como Vonage AI Studio, una de las habilidades más cruciales es comprender y crear "rutas de objetos".

¿Qué es una ruta de objetos?

Una ruta de objeto es una secuencia de claves que usted sigue para navegar a través de un objeto JSON y llegar a los datos específicos que desea. Piense en una ruta de objeto como una ruta GPS que le lleva a la pieza exacta de información que necesita dentro de una estructura JSON. Por ejemplo, en un objeto JSON que represente a una persona, la ruta de objeto para encontrar su correo electrónico podría tener el siguiente aspecto person.contact.email.

Cómo construir una trayectoria de objetos

1. Empezar por la raíz: La raíz de un objeto JSON es su nivel más externo. Desde aquí, identificas la primera clave que te acerca a tus datos.

2. Navegar por las capas: Si el valor de una clave es otro objeto o una matriz, se continúa especificando la siguiente clave o índice de matriz.

3. Repita la operación hasta obtener los datos: Continúe especificando claves o índices hasta que llegue a los datos que necesita.

Ejemplo práctico en Vonage AI Studio

Utilicemos una respuesta JSON sencilla para ilustrar cómo construir una ruta de objeto. Imagina que tienes la siguiente respuesta JSON de una API de 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: Supongamos que queremos extraer el/los artículo/s excluido/s en el pedido de hamburguesas.

• Construcción de la ruta de objetos ampliada:

  1. Empezar por la raíz: La clave raíz es order.

  2. Primera capa: Dentro de ordernavegamos hasta details.

  3. Segunda capa: En detailsencontramos customizations.

  4. Destino final: El objeto customizations objeto contiene la clave exclude.

• Recorrido final del objeto: La ruta del objeto para encontrar la lista de salsas es order.details.customizations.exclude.

Cómo utilizar rutas de objetos en Vonage AI Studio

En Vonage AI Studio, cuando configures asignaciones de respuesta o nodos en el nodo webhook, a menudo necesitarás especificar estas rutas de objetos para indicarle a Studio exactamente dónde encontrar y extraer los datos que necesitas de una respuesta de API. Las rutas de objetos son esenciales porque te permiten localizar y extraer sólo los datos que necesitas de estructuras JSON potencialmente complejas, haciendo que el manejo de los datos sea eficiente y sin errores.

Cómo pasar/añadir parámetros de consulta a las solicitudes API

En esta sección, exploraremos cómo establecer parámetros en las interacciones de la API es similar a personalizar su pedido de comida. Al igual que puede especificar cómo desea su hamburguesa en un restaurante, los parámetros en una solicitud de API le permiten definir exactamente qué datos necesita. Utilizaremos una analogía sencilla de pedir una hamburguesa para explicar este concepto, junto con un conjunto de datos de ejemplo para ilustrar cómo se aplica en un escenario práctico.

Ejemplo: Un pedido de hamburguesas

Imagina que estás en Bob's Burgers y quieres pedir una hamburguesa. Sin embargo, no te gustan los pepinillos. Así que le dices al camarero: "Quiero una hamburguesa con queso, pero no me ponga pepinillos". En este caso, "sin pepinillos" es una petición especial o un parámetro que personaliza tu pedido.

¿Qué son los parámetros de consulta?

• Analogía del mundo real: Los parámetros de consulta son como sus preferencias en un pedido de comida. Cuando pides algo específico, como una hamburguesa sin pepinillos, estás estableciendo parámetros para tu pedido.

• En términos de API: Los parámetros son los valores que envía con su solicitud de API. Dictan qué información desea obtener de la API. Por ejemplo, si solicita información sobre un usuario, un parámetro podría ser el ID del usuario. Le permiten personalizar su solicitud de datos. El uso de parámetros le permite obtener exactamente y sólo lo que necesita de una API.

Traducción a parámetros API

• Solicitud de API: En el mundo de las API, una solicitud es como su pedido a la cocina. Los detalles que proporcione (como "sin pepinillos") son parámetros que personalizan esta solicitud.

• Establecer parámetros: Cuando especifica ciertos detalles en su solicitud de API, está estableciendo parámetros. Estos parámetros indican a la API exactamente cómo "preparar" sus datos.

Configuración de parámetros en Vonage AI Studio

1. Identifique sus necesidades de datos: Comprenda qué información específica necesita de la API y qué información es capaz de proporcionar. Por ejemplo, si pides una pizza en Bob's Burgers, la cocina te devolverá un error porque no es un parámetro de consulta que sepa manejar.

2. Usa la interfaz de Vonage AI Studio: El estudio ofrece una manera intuitiva de establecer parámetros. Por ejemplo, si buscas datos de usuarios, puedes establecer un parámetro para el "userID".

3. Introduzca los valores de sus parámetros: Estos valores deben coincidir con los datos que está intentando recuperar. En nuestro ejemplo, sería el ID real del usuario.

Datos de muestra para la solicitud API

Vamos a crear un conjunto de datos de muestra para visualizarlo:

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

Ejemplo práctico: Personalización de tu pedido en Vonage AI Studio

1. Pedido inicial: Utilizando los datos del ejemplo, su pedido inicial es una hamburguesa con queso, lechuga y tomate.

2. Establecer parámetros para la personalización: Supongamos que no quieres pepinillos en tu hamburguesa. En una configuración de API, como Vonage AI Studio, agregarías 'pepinillos' al parámetro 'excluir'.

3. Datos de pedido modificados:

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

   Copia

4. Resultado: La API procesa esta solicitud y devuelve una respuesta que refleja su pedido personalizado: una hamburguesa con queso, lechuga y tomate, pero sin pepinillos.

Este es el aspecto que tendría en una tabla de base de datos:

Únete a la "Lista de invitados" de Vonage Burger

En este artículo, aprendimos lo esencial para manejar objetos JSON, respuestas de API y mapeo de respuestas dentro de Vonage AI Studio, todo a través de ejemplos fáciles de comprender inspirados en Bob's Burgers. Si te gustó lo que leíste, únete a nuestra "hamburguesería" de desarrolladores en Slack y síguenos en Xantes conocido como Twitter. Si este blog te ha resultado útil de algún modo, comparte tu opinión y etiquétame - Me encantaría conocer tu "experiencia gastronómica".