API Request

El componente API Request permite a los usuarios enviar solicitudes HTTP (GET, POST, PATCH, PUT) a cualquier endpoint externo y recibir la respuesta para usarla en sus flujos de trabajo. Puedes configurar cabeceras, cuerpo, parámetros de consulta y tiempo de espera, o simplemente pegar un comando curl y el componente lo convertirá automáticamente en los campos correspondientes.

¿Cómo funciona?

Internamente, el componente construye una solicitud HTTP con los valores que le proporciones. Si activas el Mapping Mode, el componente procesa cada registro de un conjunto de datos de entrada y envía una solicitud por cada registro, lo que facilita la automatización de tareas en lote. Cuando la respuesta llega, el componente la devuelve como un objeto Data que puede ser usado por otros componentes, o la convierte en un Tool que un agente de IA puede invocar.

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede ser configurado de tres maneras (Fixed, Mapped, Javascript).

Body: El cuerpo que se enviará con la solicitud (para POST, PATCH, PUT). Se define como un diccionario JSON.
Ejemplo:
```
{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "active": true
}
```
Body Mode: Elige cómo configurar el cuerpo:
- JSON format
- Crear manualmente con campos individuales
- FORM (x-www-form-urlencoded)
Curl: Pega un comando curl para que el componente configure automáticamente cabeceras y cuerpo.

Headers: Las cabeceras que se enviarán con la solicitud, definidas como un diccionario.
Ejemplo:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer your-token",
  "User-Agent": "MyApp/1.0"
}

Headers Mode: Elige cómo configurar las cabeceras: JSON format o crear manualmente con campos individuales.
Mapping Mode: Activa el modo de mapeo para procesar múltiples registros en lote.
Method: El método HTTP a usar (GET, POST, PATCH, PUT).
Number of Body Fields: Número de campos que se añadirán al cuerpo (para POST, PATCH, PUT).
Number of Headers: Número de cabeceras que se añadirán a la solicitud.
Number of Query Parameters: Número de parámetros de consulta que se añadirán a la URL.
Query Parameters: Los parámetros de consulta a añadir a la URL, definidos como un diccionario.
Ejemplo:
```
{
  "search": "term",
  "limit": "10",
  "page": "1",
  "sort": "desc"
}
```
Query Parameters Mode: Elige cómo configurar los parámetros de consulta: JSON format o crear manualmente con campos individuales.
Timeout: Tiempo máximo (en segundos) que la solicitud puede tardar antes de abortarse.
URLs: Una o más URLs separadas por comas.
Tool Name: El nombre del “tool” que se usará cuando este componente se conecte como herramienta. Se mostrará al agente cuando elija herramientas.
Tool Description: Descripción detallada de lo que hace esta herramienta, para que el agente la entienda.
Tools arguments metadata: Metadatos que definen los argumentos que la herramienta acepta.

Salidas

Data: Devuelve los datos recibidos de la respuesta HTTP. Se puede usar en otros componentes o en lógica de negocio.
Tool: Convierte la configuración en un “tool” que un agente de IA puede invocar, facilitando la integración con flujos de IA.

Ejemplo de Uso

Supongamos que quieres obtener la lista de usuarios de un servicio externo y filtrar por nombre:

URLs: https://api.example.com/users
Method: GET
Query Parameters:
```
{
  "search": "John",
  "limit": "10"
}
```
Headers:
```
{
  "Authorization": "Bearer abc123"
}
```
Timeout: 30

Con estos valores, el componente enviará una solicitud GET a https://api.example.com/users?search=John&limit=10 con la cabecera de autorización y devolverá la respuesta en la salida Data.

Si necesitas enviar datos a un endpoint, cambia el Method a POST, añade el Body y selecciona el Body Mode adecuado.

Componentes Relacionados

HTTP Request – Versión más básica sin opciones de mapeo.
JSON Parser – Para extraer campos específicos de la respuesta JSON.
Data Mapper – Para transformar la salida antes de usarla en otro componente.

Consejos y Mejores Prácticas

Usa el modo de mapeo cuando necesites procesar listas de datos; evita enviar una solicitud por cada registro manualmente.
Define cabeceras comunes (por ejemplo, Content-Type: application/json) en el campo Headers para evitar errores de formato.
Limita el número de Body Fields y Query Parameters a lo necesario; demasiados pueden hacer la solicitud lenta.
Configura un Timeout razonable (por ejemplo, 30–60 segundos) para evitar bloqueos en flujos largos.
Prueba con un comando curl primero; el campo Curl te ahorrará tiempo al generar automáticamente cabeceras y cuerpo.

Consideraciones de Seguridad

No expongas tokens sensibles en la interfaz; usa variables de entorno o almacenes seguros de Nappai.
Valida la URL antes de enviarla para evitar ataques de inyección de URL.
Revisa los headers para asegurarte de que no se envíen datos confidenciales accidentalmente.
Controla los timeouts para evitar que una solicitud lenta bloquee todo el flujo.

Con esta guía, podrás integrar cualquier API externa en tus flujos de Nappai de forma rápida y segura.