Solicitud API
Consulta un software externo a través de su interfaz web durante la llamada, guarda la respuesta en variables, y toma la salida Error en cuanto tarda o falla.
En resumen
| Salidas | OK y Error |
| Campos | Método, Timeout, URL, Cabeceras (1/línea), Cuerpo (POST/PUT), y una tabla de extracciones Variable y Ruta JSON |
| Métodos | GET, POST, PUT, DELETE |
| Timeout propuesto | 2, 3, 5, 8 o 10 s, 5 s por defecto |
| Timeout realmente aplicado | 8 segundos como máximo, aunque elija 10 |
| Espera de establecimiento de la conexión | 2 segundos |
| Redirecciones seguidas | 2 |
| Disyuntor | 5 fallos consecutivos en un mismo servidor abren el circuito durante 30 segundos |
El texto de ayuda mostrado en la ventana es: «Consulta una API HTTP y extrae valores JSON en variables. Si la API falla o supera el timeout, se toma la salida "Error". Utilice {{variable}} en la URL, las cabeceras y el cuerpo.»
Cómo funciona
Qué es una API
Una API es la puerta de servicio de un software: una dirección web que otro programa consulta, y que responde no con una página para leer, sino con un dato estructurado. La mayoría responde en JSON, un formato que ordena la información por nombre, a la manera de un formulario: {"cliente": {"nombre": "Pérez", "estatus": "premium"}}.
El módulo envía la solicitud, lee la respuesta y extrae lo que le interesa.
Las variables en la solicitud
La URL, las Cabeceras y el Cuerpo aceptan {{variable}}, sustituidas justo antes del envío. Así es como se consulta el servicio sobre el llamante en curso: https://api.ejemplo.com/cliente/{{caller}}.
La extracción
La respuesta rara vez se toma en bloque. La tabla de abajo asocia una Ruta JSON a un nombre de Variable. La ruta se lee de fuera hacia dentro, los niveles separados por puntos: cliente.nombre va a buscar nombre dentro de cliente. Una lista se recorre por su posición, empezando en cero: 0.nombre designa el nombre del primer elemento.
Una ruta dejada vacía devuelve la respuesta entera: es lo que hace falta cuando el servicio responde directamente un número o una palabra, sin estructura alrededor.
Una ruta que no lleva a nada da una variable vacía, sin error. La salida OK se toma de todos modos, puesto que el servicio sí ha respondido.
Cuándo se toma la salida Error
- la URL está vacía;
- el servicio no responde dentro del plazo;
- responde con un código de error, es decir cualquier código fuera de la familia de los éxitos;
- el disyuntor está abierto.
El disyuntor
Un servicio caído no debe ralentizar todas sus llamadas. Tras 5 fallos consecutivos hacia un mismo servidor, el módulo deja de llamarlo durante 30 segundos: la salida Error se toma de inmediato, sin esperar el plazo y sin siquiera enviar la solicitud. Un primer éxito reinicia el contador a cero.
Es una protección, y eso explica una observación desconcertante: durante esos treinta segundos, la llamada vuelve en Error en un abrir y cerrar de ojos, aunque el servicio quizá ya se haya recuperado.
Qué hay que indicar
| Campo | Qué se espera | Si lo deja vacío |
|---|---|---|
| Método | GET para leer, POST o PUT para enviar, DELETE para eliminar | GET |
| Timeout | el plazo de espera, reducido a 8 s como máximo en la ejecución | 5 s |
| URL | la dirección completa, que acepta {{variable}} | se toma la salida Error sin que parta ninguna solicitud |
| Cabeceras (1/línea) | una cabecera por línea, por ejemplo una clave de autenticación | no se envía ninguna cabecera |
| Cuerpo (POST/PUT) | el contenido enviado, generalmente JSON | ningún contenido; el cuerpo se ignora de todos modos en GET |
| Variable de una extracción | el nombre bajo el que guardar el valor leído | la línea se ignora |
| Ruta JSON de una extracción | la ruta hacia el valor, por ejemplo cliente.nombre | la respuesta entera se guarda en la variable |
El botón Añadir una extracción crea una línea, Eliminar retira la suya, Guardar cierra la ventana.
Procedimiento
- Obtenga de su proveedor la dirección a consultar, la forma de autenticarse, y un ejemplo de respuesta. Sin un ejemplo de respuesta, no podrá escribir las rutas de extracción.
- Coloque el módulo Solicitud API y conecte el nodo anterior a su entrada.
- Ábralo, elija el Método y ajuste el Timeout lo más corto que su servicio soporte.
- Escriba la URL, insertando las variables desde el panel Variables disponibles.
- Rellene las Cabeceras, una por línea, generalmente la línea de autenticación proporcionada por el proveedor.
- Para un POST o un PUT, escriba el Cuerpo.
- Haga clic en Añadir una extracción y asocie una Ruta JSON a un nombre de Variable, tantas veces como valores haya que recuperar.
- Haga clic en Guardar, y luego conecte OK hacia la continuación normal y Error hacia un repliegue que trate la llamada sin el dato.
- Coloque un módulo Depuración después de la salida OK, con las variables extraídas como mensaje, para leer lo que realmente se ha recibido.
- Haga clic en Guardar, y luego en Aplicar los cambios en la barra superior.
- Llame a su número, y luego abra el Registro de depuración del plan y compruebe los valores extraídos.
Si no funciona
Todas las llamadas salen en Error aunque la URL funciona en un navegador. Un navegador envía sus cookies de sesión, el módulo no. Compruebe la cabecera de autenticación. Compruebe después la URL una vez sustituidas las variables: un {{nombre}} mal escrito se convierte en vacío y produce una dirección incompleta. Por último, cualquier respuesta fuera de la familia de los éxitos cuenta como un fallo, incluida una página de error legible.
La salida Error se toma al instante, sin que se llame al servicio. El disyuntor está abierto: cinco fallos consecutivos hacia este servidor lo han hecho saltar durante treinta segundos. Espere medio minuto antes de sacar conclusiones, y luego vuelva a llamar.
He elegido 10 segundos y la llamada continúa a los 8. El plazo está limitado a ocho segundos en la ejecución, sea cual sea el valor elegido. Es intencionado: más allá, el llamante ya ha colgado.
La variable extraída está vacía aunque la respuesta contiene el dato. La ruta no corresponde. Los niveles se separan por puntos, las listas se cuentan desde cero, y una ruta vacía devuelve la respuesta entera. Extraiga primero la respuesta entera en una variable, léala en el Registro de depuración, y luego escriba la ruta exacta.
La llamada se corta cuando el servicio no responde. La salida Error no está conectada a nada. Conéctela, como mínimo hacia la bienvenida habitual.
Cómo se construye el plan de llamadas, explicado con imágenes
Ver la página Planes de numeración