Insomnia — qu'est-ce que c'est, client REST et GraphQL en développement

Qu'est-ce qu'Insomnia et ses caractéristiques clés

Insomnia est une application multiplateforme (Electron) pour envoyer des requêtes HTTP et déboguer des API. Il est développé par la société Kong depuis 2016 comme une alternative à Postman axée sur la vitesse et la confidentialité : les données sont stockées localement, la synchronisation cloud est facultative et nécessite une inscription.

Interface et navigation

La fenêtre principale est divisée en trois colonnes : à gauche se trouve l'arborescence des requêtes (Workspace), au centre l'éditeur de requêtes avec les onglets Params, Headers, Body, à droite le panneau de réponse avec les modes Pretty, Raw et Preview. Le thème sombre est activé par défaut et des thèmes personnalisés sont pris en charge via des variables CSS.

Génération de code

Insomnia prend en charge l'exportation d'une requête en code dans plus de 20 langages et frameworks : cURL, HTTPie, Python Requests, JavaScript Fetch/Axios, Kotlin OkHttp, Swift URLSession, Java Unirest, Ruby Net::HTTP et autres. Le générateur tient compte des en-têtes, du corps de la requête et du type d'authentification, ce qui accélère l'intégration de l'API dans le code de l'application.

Insomnia vs Postman : comparaison des clients API

Insomnia et Postman résolvent la même tâche mais avec des priorités différentes. Insomnia est plus léger (~80 Mo contre ~300 Mo), démarre plus vite et fonctionne entièrement hors ligne sans imposer d'inscription. Postman propose un écosystème plus mature avec surveillance, serveurs mock et workspaces d'équipe.

Choix de l'outil selon la tâche

Pour le développement individuel et les tests rapides d'endpoints, Insomnia est plus pratique grâce à sa légèreté et à l'absence d'inscription. Pour le travail en équipe avec une collection partagée, l'intégration CI/CD et la surveillance des API de production, Postman reste la norme de l'industrie.

Organisation de l'espace de travail et des environnements

Le workspace dans Insomnia contient une arborescence de requêtes divisée en dossiers. Chaque requête peut être de type HTTP, GraphQL, WebSocket ou gRPC. Le glisser-déposer, la duplication et le regroupement des requêtes par étiquettes de couleur sont pris en charge. Le fichier de configuration du workspace est stocké au format JSON.

Variables d'environnement avec héritage

Insomnia prend en charge les environnements imbriqués (Sub Environments) qui héritent des variables du parent. Cela permet de définir une URL de base dans l'environnement global et de ne redéfinir que les paramètres qui diffèrent pour différents environnements. Les variables sont substituées via la syntaxe {`{`}_variable${`}`}.

// Exemple de structure d'un environnement Insomnia
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

Travailler avec GraphQL dans Insomnia

Insomnia fournit l'un des meilleurs éditeurs GraphQL parmi les clients API. L'onglet GraphQL Query permet d'écrire des requêtes avec autocomplétion des champs sur la base du schéma chargé. À droite, la documentation sur les types, les champs et les arguments est affichée en temps réel.

Chargement du schéma et introspection

Le schéma est chargé via une requête GraphQL Introspection vers l'endpoint. Insomnia met le schéma en cache localement et le met à jour automatiquement lors des modifications. Après le chargement, l'autocomplétion (Ctrl+Espace), la validation de la requête et l'aperçu des erreurs possibles avant l'envoi deviennent disponibles.

# Requête GraphQL avec variables dans Insomnia
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

Plugins et extension des fonctionnalités

Insomnia Plugin Hub contient plus de 100 plugins qui étendent les fonctionnalités du client. Les plugins s'installent via le menu Preferences → Plugins ou manuellement via npm. Les catégories populaires incluent la génération de données de test, l'exportation vers différents formats et des validateurs de réponse personnalisés. Chaque plugin passe par une modération obligatoire avant publication dans le hub public des développeurs.

Plugins populaires

• insomnia-plugin-faker — génération de fausses données (nom, e-mail, téléphone) pour les requêtes de test.
• insomnia-plugin-aws4 — signature de requêtes avec AWS Signature Version 4 pour travailler avec Amazon API Gateway et S3.
• insomnia-plugin-utils — utilitaires pour travailler avec les dates, le hachage et le codage Base64 directement dans les requêtes.

Les plugins sont écrits en JavaScript et interagissent avec Insomnia via l'API de templating (response.*, request.*, environment.*). Développer un plugin nécessite des connaissances de base en Node.js et une publication via un paquet npm avec le tag insomnia-plugin.

CLI et automatisation des tests

Inso CLI est un utilitaire console intégré à Insomnia pour exécuter des requêtes et des tests depuis le terminal. Inso exécute des requêtes individuelles ou des collections entières, exporte les résultats en JSON et peut s'intégrer dans des pipelines CI/CD. La commande inso run collection exécute séquentiellement toutes les requêtes d'une collection.

Exemple d'intégration dans GitHub Actions

Inso CLI fonctionne dans des conteneurs Docker et en mode headless, ce qui permet de l'utiliser dans GitHub Actions et GitLab CI. La configuration de lancement est décrite dans un fichier YAML indiquant le chemin vers la collection exportée et l'environnement. Les assertions sur le code de statut et le corps de la réponse sont prises en charge via des scripts JavaScript.

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

Intégration d'Insomnia avec Git et travail en équipe

Insomnia prend en charge la synchronisation des collections via Git. Les fichiers de collection sont stockés au format JSON et peuvent être ajoutés au référentiel du projet. Insomnia fournit un client Git intégré pour visualiser les modifications, créer des commits et résoudre les conflits de fusion directement depuis l'interface.

Configuration de la synchronisation Git

Pour connecter Git, créez un dossier local avec un référentiel et indiquez-le comme répertoire racine dans les paramètres d'Insomnia. L'application suit automatiquement les modifications des fichiers de collection et les affiche dans le panneau Version Control. Les opérations standard sont prises en charge : commit, push, pull et affichage du diff entre versions.

Travail en équipe via Insomnia Cloud

Pour les projets sans Git, Insomnia propose une synchronisation cloud via Insomnia Cloud. Le forfait gratuit inclut jusqu'à 3 membres d'équipe et la sauvegarde automatique des collections. Les forfaits payants ajoutent la gestion des accès, l'audit des modifications et un support prioritaire.

Design Mode et génération de spécifications

Design Mode dans Insomnia permet de créer des spécifications d'API au format OpenAPI 3.0. Le mode fonctionne comme un éditeur visuel : définissez des endpoints et des schémas de données sans écrire de YAML à la main. La spécification peut être exportée en JSON ou en YAML.

Génération d'une collection à partir d'OpenAPI

Insomnia importe des spécifications OpenAPI et crée une collection de requêtes pour chaque endpoint. Les chemins et schémas sont convertis en requêtes HTTP prêtes à l'emploi. La fonction est utile lors de l'intégration avec des microservices, où la spécification est stockée dans un référentiel séparé de l'équipe.

Marquage des requêtes

Chaque requête peut recevoir une étiquette de couleur : red, blue, green, orange, purple. Le filtrage par tags fonctionne via la barre de recherche indépendamment de la structure des dossiers, ce qui simplifie la navigation dans les projets avec des centaines d'endpoints et de nombreux modules.

Design Mode et génération de spécifications

Design Mode dans Insomnia permet de créer des spécifications d'API au format OpenAPI 3.0 directement dans l'application. Le mode fonctionne comme un éditeur visuel : définissez des endpoints, des schémas de données et des paramètres sans écrire de YAML à la main. La spécification peut être exportée en JSON ou en YAML pour publication dans des référentiels.

Génération d'une collection à partir d'OpenAPI

Insomnia importe des spécifications OpenAPI existantes et crée automatiquement une collection de requêtes pour chaque endpoint. Les chemins et schémas sont convertis en requêtes HTTP prêtes à l'emploi avec des types de données corrects. Cette fonction est utile lors de l'intégration avec des microservices, où la spécification est stockée et maintenue par une équipe de développement backend séparée.

Marquage et filtrage des requêtes

Pour organiser un grand nombre de requêtes, Insomnia prend en charge le marquage — chaque requête peut recevoir une étiquette de couleur : red, blue, green, orange, purple. Le filtrage par tags fonctionne via la barre de recherche indépendamment de la structure des dossiers, ce qui simplifie la navigation dans les projets avec des centaines d'endpoints et de nombreux modules fonctionnels d'API.