Insomnia — qué es, cliente REST y GraphQL en el desarrollo

Qué es Insomnia y sus características clave

Insomnia es una aplicación multiplataforma (Electron) para enviar solicitudes HTTP y depurar API. La desarrolla la empresa Kong desde 2016 como una alternativa a Postman con énfasis en la velocidad y la privacidad: los datos se almacenan localmente, la sincronización en la nube es opcional y requiere registro.

Interfaz y navegación

La ventana principal se divide en tres columnas: a la izquierda está el árbol de solicitudes (Workspace), en el centro el editor de solicitudes con las pestañas Params, Headers, Body, y a la derecha el panel de respuesta con los modos Pretty, Raw y Preview. El tema oscuro está activado por defecto y se admiten temas personalizados mediante variables CSS.

Generación de código

Insomnia admite la exportación de una solicitud a código en más de 20 lenguajes y frameworks: cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP y otros. El generador tiene en cuenta las cabeceras, el cuerpo de la solicitud y el tipo de autenticación, lo que acelera la integración de la API en el código de la aplicación.

Insomnia vs Postman: comparación de clientes API

Insomnia y Postman resuelven la misma tarea pero con distintas prioridades. Insomnia es más ligero (~80 MB frente a ~300 MB), arranca más rápido y funciona totalmente sin conexión sin imponer el registro. Postman ofrece un ecosistema más maduro con monitorización, servidores mock y workspaces de equipo.

Elección de la herramienta según la tarea

Para el desarrollo individual y la prueba rápida de endpoints, Insomnia resulta más cómodo gracias a su ligereza y a la ausencia de registro. Para el trabajo en equipo con una colección compartida, la integración CI/CD y la monitorización de API de producción, Postman sigue siendo el estándar de la industria.

Organización del espacio de trabajo y los entornos

El workspace en Insomnia contiene un árbol de solicitudes dividido en carpetas. Cada solicitud puede ser de tipo HTTP, GraphQL, WebSocket o gRPC. Se admite arrastrar y soltar, duplicar y agrupar solicitudes por etiquetas de color. El archivo de configuración del workspace se almacena en formato JSON.

Variables de entorno con herencia

Insomnia admite entornos anidados (Sub Environments) que heredan las variables del padre. Esto permite definir una URL base en el entorno global y sobrescribir solo los parámetros que difieren para distintos entornos. Las variables se sustituyen mediante la sintaxis {`{`}_variable${`}`}.

// Ejemplo de la estructura de un entorno de Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Trabajo con GraphQL en Insomnia

Insomnia ofrece uno de los mejores editores de GraphQL entre los clientes API. La pestaña GraphQL Query permite escribir consultas con autocompletado de campos basado en el esquema cargado. A la derecha se muestra documentación sobre tipos, campos y argumentos en tiempo real.

Carga del esquema e Introspection

El esquema se carga mediante una solicitud GraphQL Introspection al endpoint. Insomnia guarda el esquema en caché localmente y lo actualiza automáticamente cuando cambia. Tras la carga, están disponibles el autocompletado (Ctrl+Space), la validación de la consulta y la vista previa de posibles errores antes de enviar.

# Consulta GraphQL con variables en Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugins y ampliación de funcionalidades

Insomnia Plugin Hub contiene más de 100 plugins que amplían la funcionalidad del cliente. Los plugins se instalan mediante el menú Preferences → Plugins o manualmente a través de npm. Las categorías populares incluyen la generación de datos de prueba, la exportación a distintos formatos y validadores de respuesta personalizados. Cada plugin pasa por una moderación obligatoria antes de publicarse en el hub público de desarrolladores.

Plugins populares

• insomnia-plugin-faker — generación de datos falsos (nombre, email, teléfono) para solicitudes de prueba.
• insomnia-plugin-aws4 — firma de solicitudes con AWS Signature Version 4 para trabajar con Amazon API Gateway y S3.
• insomnia-plugin-utils — utilidades para trabajar con fechas, hash y codificación Base64 directamente en las solicitudes.

Los plugins se escriben en JavaScript e interactúan con Insomnia mediante la API de plantillas (response.*, request.*, environment.*). Desarrollar un plugin requiere conocimientos básicos de Node.js y la publicación mediante un paquete npm con la etiqueta insomnia-plugin.

CLI y automatización de pruebas

Inso CLI es una utilidad de consola integrada en Insomnia para ejecutar solicitudes y pruebas desde el terminal. Inso ejecuta solicitudes individuales o colecciones completas, exporta los resultados a JSON y puede integrarse en pipelines CI/CD. El comando inso run collection ejecuta secuencialmente todas las solicitudes de una colección.

Ejemplo de integración en GitHub Actions

Inso CLI funciona en contenedores Docker y en modo headless, lo que permite usarlo en GitHub Actions y GitLab CI. La configuración de ejecución se describe en un archivo YAML indicando la ruta a la colección exportada y el entorno. Se admiten aserciones sobre el código de estado y el cuerpo de la respuesta mediante scripts JavaScript.

# Workflow de GitHub Actions con Inso CLI
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

Integración de Insomnia con Git y trabajo en equipo

Insomnia admite la sincronización de colecciones a través de Git. Los archivos de colección se almacenan en formato JSON y pueden añadirse al repositorio del proyecto. Insomnia proporciona un cliente Git integrado para ver los cambios, crear commits y resolver conflictos de fusión directamente desde la interfaz.

Configuración de la sincronización con Git

Para conectar Git, cree una carpeta local con un repositorio y señálela como directorio raíz en la configuración de Insomnia. La aplicación rastrea automáticamente los cambios en los archivos de colección y los muestra en el panel Version Control. Se admiten operaciones estándar: commit, push, pull y visualización del diff entre versiones.

Trabajo en equipo mediante Insomnia Cloud

Para proyectos sin Git, Insomnia ofrece sincronización en la nube mediante Insomnia Cloud. El plan gratuito incluye hasta 3 miembros del equipo y copia de seguridad automática de las colecciones. Los planes de pago añaden gestión de accesos, auditoría de cambios y soporte prioritario.

Design Mode y generación de especificaciones

Design Mode en Insomnia permite crear especificaciones API en formato OpenAPI 3.0. El modo funciona como un editor visual: defina endpoints y esquemas de datos sin escribir YAML a mano. La especificación puede exportarse a JSON o YAML.

Generación de una colección a partir de OpenAPI

Insomnia importa especificaciones OpenAPI y crea una colección de solicitudes para cada endpoint. Las rutas y los esquemas se convierten en solicitudes HTTP listas para usar. La función es útil al integrarse con microservicios donde la especificación se almacena en un repositorio separado del equipo.

Etiquetado de solicitudes

A cada solicitud se le puede asignar una etiqueta de color: red, blue, green, orange, purple. El filtrado por etiquetas funciona mediante la barra de búsqueda independientemente de la estructura de carpetas, lo que simplifica la navegación en proyectos con cientos de endpoints y muchos módulos.

Design Mode y generación de especificaciones

Design Mode en Insomnia permite crear especificaciones API en formato OpenAPI 3.0 directamente dentro de la aplicación. El modo funciona como un editor visual: defina endpoints, esquemas de datos y parámetros sin escribir YAML a mano. La especificación puede exportarse a JSON o YAML para publicarla en repositorios.

Generación de una colección a partir de OpenAPI

Insomnia importa especificaciones OpenAPI existentes y crea automáticamente una colección de solicitudes para cada endpoint. Las rutas y los esquemas se convierten en solicitudes HTTP listas para usar con tipos de datos correctos. Esta función es útil al integrarse con microservicios donde la especificación se almacena y mantiene un equipo de desarrollo de backend separado.

Etiquetado y filtrado de solicitudes

Para organizar un gran número de solicitudes, Insomnia admite el etiquetado: a cada solicitud se le puede asignar una etiqueta de color: red, blue, green, orange, purple. El filtrado por etiquetas funciona mediante la barra de búsqueda independientemente de la estructura de carpetas, lo que simplifica la navegación en proyectos con cientos de endpoints y muchos módulos funcionales de API.