Probar APIs HTTP (.lnh)

Archivo → Nuevo → Nueva prueba de API abre un cliente HTTP guardado en un archivo .lnh. Un archivo representa un endpoint (método, URL, cabeceras y cuerpo) y mantiene varias pruebas en la lista de la izquierda — cada prueba con sus valores para las variables {nombre} usadas en la URL, las cabeceras y el cuerpo, más el resultado de la última ejecución (estado, tiempo, fecha, cabeceras y cuerpo de la respuesta). También muestra el comando curl equivalente. La misma operación puntual está disponible vía CLI (http) y MCP (http_request). El probador usa curl, que ya viene con Windows 10 y 11; si falta, LightNote abre la guía de instalación antes de enviar.

Enviar y leer la respuesta

Ctrl+Enter envía la petición. Mientras la respuesta no vuelve, el mismo botón pasa a ser Detener (o Esc) y la espera muestra los segundos. La etiqueta de la respuesta trae el estado y el tiempo; al lado van el tipo, el tamaño y cuándo se ejecutó la prueba. La línea curl sigue lo que escribes, ya con las variables de la prueba seleccionada: el botón de al lado copia el comando, y su flecha ofrece lo mismo en PowerShell, Python, JavaScript, C# y HTTPie. Pegar un comando curl directamente en la URL importa el método, las cabeceras y el cuerpo sin borrar las pruebas.

Una variable sin valor en la prueba se envía literal ({id} en la URL, y el servidor responde con un error que no dice por qué): la pestaña Variables la destaca y dice su nombre. El punto junto a cada prueba en la lista tiene el color del último estado, y el anillo vacío es una prueba que aún no se ejecutó. En la respuesta, la barra sobre el cuerpo formatea JSON/XML solo en pantalla, ajusta las líneas, copia el cuerpo y lo guarda en un archivo tal como llegó.

Armar la solicitud. La pestaña Parámetros muestra la query de la URL como lista: editar una fila cambia la URL, y editar la URL cambia la lista. La pestaña Autenticación arma la cabecera por ti — Basic, Bearer o Clave de API, en una cabecera o en la URL — y cada campo acepta una {variable}, para que el secreto viva en el entorno y no en el archivo; si la pestaña Cabeceras ya tiene la misma cabecera, vale la que está allí. En el Cuerpo, el Tipo elige JSON, XML, SOAP, formulario, multipart (campos de texto y archivos) o un archivo enviado en binario, y el Content-Type se añade solo cuando no escribiste uno. Una ruta de archivo relativa cuenta desde la carpeta del .lnh. Con multipart o archivo, la flecha del botón de copiar deja PowerShell y JavaScript en gris, porque no saben enviar ese cuerpo. La pestaña Opciones cambia el tiempo límite (60 s por defecto) y hace que la solicitud siga las redirecciones; sin eso, la respuesta que se muestra es el propio 3xx. Abierto en una versión anterior de LightNote, el archivo se envía sin la autenticación y sin el tipo, y nunca como una solicitud distinta. Para un servidor local con certificado propio, No verificar el certificado (HTTPS) desactiva la verificación: mientras esté activada, la línea de la respuesta dice certificado no verificado, y lnote http-run también lo dice en el informe.

Leer la respuesta. El cuerpo se abre en un editor de código de solo lectura, resaltado según el tipo de la respuesta, con plegado de bloques y la búsqueda de la ventana (Ctrl+F). La pestaña Cookies lista lo que el servidor pidió guardar, y la Línea de tiempo muestra la solicitud exacta que salió —con las cabeceras que añadió el propio curl— y las cabeceras crudas de la respuesta. La línea de tiempo queda solo en memoria: repite el Authorization, y el archivo va a Git.

Verificaciones

La pestaña Verificaciones dice si la prueba pasó. Cada fila compara una parte de la respuesta —el estado, una cabecera, el cuerpo completo, una ruta JSONPath ($.usuario.id, $.items[0].nombre, $.items.length()), una ruta XPath (//Precio, count(//Item)) o el tiempo en milisegundos— con el valor esperado: igual, distinto, mayor, menor, contiene, coincide con una expresión regular, existe o es de un tipo. En XPath el prefijo del nombre se ignora, así que soap:Envelope y Envelope son el mismo paso. Con verificaciones, son ellas las que deciden el resultado: un 404 esperado pasa, y un 200 con el campo equivocado falla. El resultado de cada una aparece en la última columna, el resumen va junto a la etiqueta de la respuesta y el punto de la prueba en la lista se pone verde o rojo. Desmarcar una fila la mantiene en el archivo sin contar en el resultado.

El botón de reproducir en la parte superior de la lista ejecuta todas las pruebas del archivo, una a una, y dice cuántas pasaron. Cuando una prueba se ha ejecutado dos veces, el botón de comparar sobre el cuerpo de la respuesta abre la ejecución anterior y la actual lado a lado, con el cuerpo formateado en ambos lados. Solo se guarda la ejecución anterior: el archivo va a Git, y un historial largo llenaría cada diff.

Entornos, capturas y la carpeta entera

Los entornos usan el formato abierto de JetBrains y VS Code: un http-client.env.json en la carpeta (o por encima) con un objeto por entorno — {"dev": {"host": "http://localhost:8080"}} — y, al lado, un http-client.private.env.json con los secretos, para dejarlos fuera de Git. En el mismo entorno gana el privado, y $shared vale para todos. El selector junto a la URL elige el entorno, y el menú de importar y exportar crea el archivo. Una variable sale de la prueba, luego de la captura y luego del entorno, y la pestaña Variables dice de dónde vino cada una.

La pestaña Capturas guarda un trozo de la respuesta como variable —el token de un inicio de sesión, el id de un recurso recién creado— para las pruebas siguientes de este archivo y de los demás de la misma carpeta. Así un .lnh de inicio de sesión alimenta la llamada autenticada de otro. El valor capturado queda solo en memoria y nunca va al archivo.

La carpeta es la colección: lnote http-run --path <carpeta> --env dev ejecuta todos sus .lnh en orden natural (01-login antes de 02-perfil) y termina con error cuando alguna prueba falla, lo que sirve a un CI. La misma ejecución está en MCP como http_test_run, para que el agente de IA ejecute las pruebas que escribiste. Por defecto los archivos no cambian; --save guarda en ellos el último resultado de cada prueba.

Importar y exportar

Importar y exportar OpenAPI. El botón de flechas en la parte superior de la lista de pruebas abre Importar OpenAPI… y Exportar OpenAPI…. La importación lee una especificación en YAML o JSON en las tres generaciones en uso — Swagger 2.0, OpenAPI 3.0 y 3.1 — y arma la prueba sola: los {parámetros} de la ruta ya usan la misma sintaxis que las variables {nombre} del .lnh, los ejemplos declarados pasan a ser los valores de la prueba, el esquema de seguridad se convierte en la cabecera Authorization y cada servidor declarado se convierte en una prueba propia (homologación y producción lado a lado). Como un .lnh guarda un endpoint, una especificación con varias operaciones pregunta cuál importar — o guarda todas a la vez, un archivo .lnh por operación.

La exportación hace el camino inverso y genera una especificación OpenAPI 3.0.3 a partir del archivo: servidores, parámetros y cuerpo salen de la plantilla, y las respuestas de ejemplo salen de las ejecuciones registradas. Es un esqueleto, no un contrato completo — el .lnh describe llamadas, así que tipos, descripciones y esquemas no se reconstruyen. Sus pruebas viajan en el campo x-lightnote-tests, y por eso vuelven intactas al reimportar el archivo.

Importar un comando curl. En el mismo botón, Importar comando curl… abre un cuadro para pegar — de ahí viene el comando, no del disco, y el campo ya viene relleno cuando hay un curl en el portapapeles. Entiende los tres dialectos en los que circula el mismo comando: el de Copiar como cURL de Chrome/Firefox (comillas simples), el de Copy as cURL (cmd) en Windows (con ^) y el ejemplo de documentación cortado con \. El método sale del -X — o se deduce: POST cuando hay cuerpo, GET cuando no.

La importación es literal: ningún valor se convierte solo en una variable {nombre}, porque adivinar qué token es un secreto fallaría. Algunos casos avisan en vez de mentir — un cuerpo que viene de un archivo (-d @archivo) no se puede leer, y el envío multipart (-F) no se reproduce fielmente, así que los campos van al cuerpo como texto para que los ajuste.

Importar desde otra herramienta. Importar desde otra herramienta… lee un archivo .http/.rest (REST Client de VS Code, JetBrains, Visual Studio), la colección o el entorno de Postman, la exportación de Insomnia (v4 en JSON o v5 en YAML), el HAR que el navegador guarda con Guardar todo como HAR, el .bru de Bruno (o la carpeta entera, con Importar carpeta de Bruno…) y el WSDL de un servicio SOAP. El formato se reconoce por el contenido, no por la extensión. Cada petición se convierte en un .lnh y las carpetas de la colección en carpetas: elija una para este archivo o guárdelas todas de una vez. {{name}} se convierte en {name}, la autenticación en cabecera, los entornos van al http-client.env.json (lo que el origen marca como secreto va al .private) sin cambiar ningún valor que ya estuviera allí, y las verificaciones y capturas de Bruno — y el pm.response.to.have.status de Postman — se convierten en verificaciones y capturas de aquí. Del HAR solo entran las llamadas de API y la página, con la respuesta que recibió el navegador como última ejecución; del WSDL sale un sobre SOAP por operación, con el SOAPAction y cada campo como variable.

Lo que no tiene equivalente se deja como está y se indica: los scripts de antes y después de la petición no se convierten, las variables dinámicas ({{$guid}}) y los encadenamientos siguen literales, y el Basic con variable, el cuerpo multipart y el cuerpo de archivo van a la pestaña Autenticación y al Tipo del cuerpo, con la ruta del archivo, que vino de la otra máquina, listada para revisarla. Al guardar la colección, ese informe se convierte en una nota en la carpeta de destino. Exportar como .http… hace el camino inverso con la prueba seleccionada: la plantilla con {{name}} y los valores como @name = valor.