Módulo Http

El módulo Http proporciona un cliente REST ligero y multiplataforma para realizar peticiones HTTP/HTTPS desde tus programas JARU. Este módulo está diseñado específicamente para comunicación con APIs REST, servicios web y endpoints IoT, permitiendo enviar y recibir datos de forma sencilla tanto desde la VM de Windows como desde dispositivos ESP32.

JARU HTTP Module

El cliente Http es ideal para proyectos IoT que necesitan comunicarse con servidores en la nube, APIs de terceros, o servicios backend propios. Soporta los métodos GET y POST, cabeceras personalizadas, y proporciona información detallada sobre el estado de las peticiones.

Uso

use Http

Funciones

get

La función get(url) realiza una petición HTTP GET a la URL especificada y devuelve el cuerpo de la respuesta como una cadena de texto.

Http.get(url)

Parámetros

Parámetro	Tipo	Descripción
`url`	string	URL completa del recurso (incluyendo `http://` o `https://`)

Retorno

Tipo	Descripción
`string`	Cuerpo de la respuesta si la petición fue exitosa
`nil`	Si ocurrió un error (usar `error()` para obtener detalles)

Ejemplo básico

use Http

var respuesta = Http.get("https://api.ejemplo.com/datos")

if (respuesta != nil) then
    println("Respuesta: ", respuesta)
else
    println("Error: ", Http.error())
end

post

La función post(url, body [, contentType]) realiza una petición HTTP POST enviando datos al servidor.

Http.post(url, body)
Http.post(url, body, contentType)

Parámetros

Parámetro	Tipo	Descripción
`url`	string	URL completa del endpoint
`body`	string	Cuerpo de la petición (datos a enviar)
`contentType`	string	(Opcional) Tipo de contenido. Por defecto es `"application/json"`

Retorno

Tipo	Descripción
`string`	Cuerpo de la respuesta si la petición fue exitosa
`nil`	Si ocurrió un error

Ejemplo con JSON

use Http

var datos = '{"temperatura": 25.5, "humedad": 60}'
var respuesta = Http.post("https://api.ejemplo.com/sensores", datos)

if (respuesta != nil) then
    println("Servidor respondió: ", respuesta)
    println("Código de estado: ", Http.status())
else
    println("Error en POST: ", Http.error())
end

Ejemplo con form-urlencoded

use Http

var formData = "usuario=admin&clave=secreto"
var respuesta = Http.post(
    "https://api.ejemplo.com/login",
    formData,
    "application/x-www-form-urlencoded"
)

if (respuesta != nil) then
    println("Login exitoso: ", respuesta)
end

setHeader

La función setHeader(clave, valor) establece una cabecera HTTP personalizada que se enviará en las siguientes peticiones. Las cabeceras persisten entre llamadas hasta que se limpien con clearHeaders().

Http.setHeader(clave, valor)

Parámetros

Parámetro	Tipo	Descripción
`clave`	string	Nombre de la cabecera (ej: `"Authorization"`)
`valor`	string	Valor de la cabecera (ej: `"Bearer token123"`)

Retorno

Devuelve true siempre.

Ejemplo con autenticación

use Http

// Configurar cabecera de autorización
Http.setHeader("Authorization", "Bearer mi_token_jwt")
Http.setHeader("X-API-Key", "clave_secreta")

// Las cabeceras se enviarán en todas las peticiones siguientes
var respuesta = Http.get("https://api.ejemplo.com/recurso-protegido")

Cabeceras persistentes

Las cabeceras configuradas con setHeader() se mantienen activas para todas las peticiones posteriores. Si necesitas cabeceras diferentes para distintas APIs, usa clearHeaders() entre llamadas.

clearHeaders

La función clearHeaders() elimina todas las cabeceras personalizadas configuradas previamente.

Http.clearHeaders()

Retorno

Devuelve true siempre.

Ejemplo

use Http

// Configurar cabeceras para una API
Http.setHeader("Authorization", "Bearer token_api_1")
Http.get("https://api1.ejemplo.com/datos")

// Limpiar y configurar para otra API
Http.clearHeaders()
Http.setHeader("X-Custom-Header", "valor_diferente")
Http.get("https://api2.ejemplo.com/otros-datos")

status

La función status() devuelve el código de estado HTTP de la última petición realizada.

Http.status()

Retorno

Tipo	Descripción
`integer`	Código de estado HTTP (200, 404, 500, etc.)

Códigos de estado comunes

Código	Significado
`200`	OK - Petición exitosa
`201`	Created - Recurso creado
`400`	Bad Request - Petición mal formada
`401`	Unauthorized - No autorizado
`403`	Forbidden - Acceso prohibido
`404`	Not Found - Recurso no encontrado
`500`	Internal Server Error - Error del servidor

Ejemplo

use Http

var respuesta = Http.get("https://api.ejemplo.com/usuario/123")
var codigo = Http.status()

switch (codigo)
    case 200:
        println("Usuario encontrado: ", respuesta)
    case 404:
        println("Usuario no existe")
    case 401:
        println("No autorizado - verifica tu token")
    default:
        println("Código de respuesta: ", codigo)
end

error

La función error() devuelve el mensaje de error de la última petición fallida.

Http.error()

Retorno

Tipo	Descripción
`string`	Mensaje descriptivo del error, o cadena vacía si no hubo error

Posibles mensajes de error

Error	Descripción
`"Connection error"`	No se pudo establecer conexión con el servidor
`"Protocol error"`	Error en el protocolo HTTP
`"Read error"`	Error al leer la respuesta
`"Write error"`	Error al enviar datos
`"Invalid URL"`	La URL proporcionada no es válida
`"begin() failed"`	Error al inicializar la conexión (ESP32)

Ejemplo

use Http

var respuesta = Http.get("https://servidor-inexistente.com/api")

if (respuesta == nil) then
    var err = Http.error()
    println("La petición falló: ", err)
end

timeout

La función timeout([ms]) permite obtener o establecer el tiempo máximo de espera para las peticiones HTTP.

// Obtener timeout actual
Http.timeout()

// Establecer nuevo timeout
Http.timeout(ms)

Parámetros (modo setter)

Parámetro	Tipo	Descripción
`ms`	integer	Tiempo de espera en milisegundos

Retorno

Modo	Tipo	Descripción
Getter	`integer`	Timeout actual en milisegundos
Setter	`true`	Confirmación de que se estableció el valor

Valor por defecto

El timeout por defecto es de 10000 ms (10 segundos).

Ejemplo

use Http

// Ver timeout actual
println("Timeout actual: ", Http.timeout(), " ms")

// Aumentar timeout para APIs lentas
Http.timeout(30000)  // 30 segundos

// Petición a API que puede tardar
var respuesta = Http.get("https://api.lenta.com/proceso-largo")

Ejemplo completo: Cliente REST para IoT

use Http
use WiFi
use GPIO

// Conectar a WiFi
WiFi.connect("MiRed", "contraseña")
if (not WiFi.isConnected()) then
    println("Error: No se pudo conectar a WiFi")
    return
end
println("Conectado! IP: ", WiFi.ip())

// Configurar cliente HTTP
Http.timeout(15000)
Http.setHeader("Content-Type", "application/json")
Http.setHeader("X-Device-ID", "esp32-sensor-001")

// Configurar sensor
var sensorPin = GPIO.pin(34, GPIO.INPUT)

// Bucle principal: enviar datos cada 30 segundos
while (true)
    // Leer sensor
    var lectura = GPIO.aread(sensorPin)
    var temperatura = lectura * 0.1  // Conversión ejemplo
    
    // Preparar datos JSON
    var payload = '{"device": "esp32-001", "temp": ' + temperatura + '}'
    
    // Enviar a la API
    var respuesta = Http.post("https://api.miservidor.com/telemetria", payload)
    
    if (respuesta != nil) then
        println("Datos enviados OK. Status: ", Http.status())
    else
        println("Error enviando: ", Http.error())
    end
    
    pause(30000)  // Esperar 30 segundos
end

Ejemplo: Consumir API REST con autenticación

use Http

// Paso 1: Obtener token de autenticación
var loginData = '{"email": "usuario@ejemplo.com", "password": "clave123"}'
var tokenResp = Http.post("https://api.ejemplo.com/auth/login", loginData)

if (tokenResp == nil) then
    println("Error en login: ", Http.error())
    return
end

// Parsear token de la respuesta (simplificado)
// En un caso real usarías el módulo JSON
var token = tokenResp  // Asumiendo que la API devuelve solo el token

// Paso 2: Usar token para peticiones autenticadas
Http.setHeader("Authorization", "Bearer " + token)

// Paso 3: Obtener datos protegidos
var datos = Http.get("https://api.ejemplo.com/usuarios/perfil")

if (datos != nil and Http.status() == 200) then
    println("Perfil obtenido: ", datos)
else
    println("Error: ", Http.status(), " - ", Http.error())
end

// Paso 4: Actualizar datos
var actualizacion = '{"nombre": "Nuevo Nombre"}'
var resultado = Http.post("https://api.ejemplo.com/usuarios/perfil", actualizacion)

if (Http.status() == 200) then
    println("Perfil actualizado correctamente")
end

Ejemplo: Manejo de errores robusto

use Http

func peticionSegura(url)
    var intentos = 3
    var respuesta = nil
    
    for (var i = 0; i < intentos; i++)
        respuesta = Http.get(url)
        
        if (respuesta != nil) then
            var codigo = Http.status()
            if (codigo >= 200 and codigo < 300) then
                return respuesta  // Éxito
            elsif (codigo >= 500) then
                // Error del servidor, reintentar
                println("Error del servidor (", codigo, "), reintentando...")
                pause(2000)
            else
                // Error del cliente, no reintentar
                println("Error del cliente: ", codigo)
                return nil
            end
        else
            println("Error de conexión: ", Http.error(), ", reintentando...")
            pause(2000)
        end
    end
    
    println("Falló después de ", intentos, " intentos")
    return nil
end

// Uso
var datos = peticionSegura("https://api.ejemplo.com/datos")
if (datos != nil) then
    println("Datos: ", datos)
end

Consideraciones importantes

Conexión WiFi requerida

En ESP32, asegúrate de que el dispositivo esté conectado a una red WiFi antes de realizar peticiones HTTP. Usa el módulo WiFi para establecer la conexión.

Uso con JSON

Para trabajar con APIs REST que usan JSON, combina el módulo Http con el módulo JSON para parsear las respuestas:

use Http
use JSON

var respuesta = Http.get("https://api.ejemplo.com/datos")
if (respuesta != nil) then
    var datos = JSON.parse(respuesta)
    println("Valor: ", datos.campo)
end

HTTPS

El módulo soporta conexiones HTTPS. En ESP32, las conexiones seguras pueden requerir más memoria y tiempo de procesamiento.

Plataformas soportadas

Plataforma	Soporte	Notas
Windows (SDL2)	✅	HTTP y HTTPS completo
ESP32	✅	HTTP y HTTPS (requiere WiFi activo)
Emscripten (Web)	❌	No soportado
SiFive	🚧	En desarrollo

Uso​

Funciones​

get​

Parámetros​

Retorno​

Ejemplo básico​

post​

Parámetros​

Retorno​

Ejemplo con JSON​

Ejemplo con form-urlencoded​

setHeader​

Parámetros​

Retorno​

Ejemplo con autenticación​

clearHeaders​

Retorno​

Ejemplo​

status​

Retorno​

Códigos de estado comunes​

Ejemplo​

error​

Retorno​

Posibles mensajes de error​

Ejemplo​

timeout​

Parámetros (modo setter)​

Retorno​

Ejemplo​

Ejemplo completo: Cliente REST para IoT​

Ejemplo: Consumir API REST con autenticación​

Ejemplo: Manejo de errores robusto​

Consideraciones importantes​

Plataformas soportadas​

Uso

Funciones

get

Parámetros

Retorno

Ejemplo básico

post

Parámetros

Retorno

Ejemplo con JSON

Ejemplo con form-urlencoded

setHeader

Parámetros

Retorno

Ejemplo con autenticación

clearHeaders

Retorno

Ejemplo

status

Retorno

Códigos de estado comunes

Ejemplo

error

Retorno

Posibles mensajes de error

Ejemplo

timeout

Parámetros (modo setter)

Retorno

Ejemplo

Ejemplo completo: Cliente REST para IoT

Ejemplo: Consumir API REST con autenticación

Ejemplo: Manejo de errores robusto

Consideraciones importantes

Plataformas soportadas