Les fichiers .http offrent une alternative élégante aux outils comme Postman en permettant de décrire, versionner et exécuter des requêtes HTTP directement depuis votre éditeur de code.
Dans le développement moderne, tester les APIs est devenu une activité quotidienne. Que ce soit pour valider un endpoint fraîchement développé, déboguer une intégration externe ou documenter les points d’entrée d’un service, nous passons un temps considérable à envoyer des requêtes HTTP.
La plupart des développeurs se tournent vers des outils dédiés comme Postman ou Insomnia. Ces applications offrent des fonctionnalités complètes, mais impliquent certains compromis. Applications Electron qui consomment plusieurs centaines de Mo de RAM. Compte obligatoire pour la synchronisation. Interfaces riches en fonctionnalités, dont beaucoup restent inutilisées dans un usage quotidien.
Et si vos tests d’API vivaient directement dans votre repository, versionnés avec Git, exécutables depuis votre IDE sans application externe ?
Les fichiers .http : une convention qui s’impose
Les fichiers .http (aussi appelés fichiers REST) sont de simples fichiers texte qui décrivent des requêtes HTTP. Bien qu’il ne s’agisse pas d’un standard officiel IETF, le format a émergé comme une convention de facto dans l’écosystème des IDE modernes.
Origine et évolution du format
L’histoire du format .http commence en mars 2016 avec l’extension REST Client pour VS Code, créée par Huachao Mao. Cette extension établit la syntaxe qui deviendra la référence : un format texte simple basé sur la spécification HTTP (RFC 2616), permettant de décrire des requêtes dans des fichiers .http ou .rest versionnables.
La première validation de l’approche arrive rapidement. En septembre 2017, JetBrains annonce dans son blog le nouvel “editor-based REST client” pour IntelliJ IDEA 2017.3, reconnaissant explicitement qu’il “réutilise l’approche de VS Code et Emacs pour tester les requêtes HTTP” et que “le format de fichier est essentiellement un mélange de RFC HTTP et d’injections personnalisées, similaire à ce que VS Code utilise”.
Le tournant arrive entre 2022 et 2023 avec l’écosystème Microsoft/.NET qui propulse le format :
- Visual Studio 2022 (versions 17.5-17.6) intègre le support natif des fichiers
.http, citant explicitement l’extension VS Code REST Client comme source d’inspiration - .NET 8 (novembre 2023) : les fichiers
.httpsont désormais inclus par défaut dans tous les templates de projets ASP.NET Core Web API
Aujourd’hui, le format bénéficie d’un support natif ou via extensions dans les principaux IDE (VS Code, Visual Studio, IntelliJ IDEA, WebStorm, Rider).
Un format lisible et interopérable
Les fichiers .http reposent sur la syntaxe HTTP des RFCs officiels (RFC 2616, RFC 9110) pour décrire les requêtes, avec des extensions pratiques pour les variables (@variable = valeur), les commentaires (#), et les séparateurs de requêtes (###).
L’avantage principal réside dans la lisibilité directe : un fichier .http est du texte brut compréhensible sans outil spécifique, facilitant la revue de code et le versionnement Git. Un même fichier fonctionne dans VS Code, IntelliJ ou Visual Studio avec une compatibilité généralement élevée, sans dépendre d’un écosystème particulier.
GET https://api.example.com/users/1
Cette approche minimaliste présente plusieurs avantages structurels :
Versionnement natif : Les fichiers .http vivent dans votre repository Git. Chaque modification de l’API peut s’accompagner d’une mise à jour des requêtes de test correspondantes. Le diff Git montre exactement ce qui a changé.
Documentation vivante : Ces fichiers servent simultanément de tests manuels, de documentation technique et d’exemples d’intégration. Un nouveau développeur peut comprendre comment interagir avec l’API en lisant simplement ces fichiers.
Indépendance technologique : Aucun compte à créer, aucune synchronisation cloud, aucune dépendance à un service tiers. Juste des fichiers texte que n’importe quel éditeur peut lire.
Collaboration simplifiée : Partagez vos requêtes via pull request. Reviewez les modifications d’API comme vous reviewez le code. Pas de “envoie-moi ta collection Postman” par email ou Slack.
Configuration de l’environnement
Pour exploiter les fichiers .http, vous avez besoin d’un client capable de les interpréter et d’exécuter les requêtes.
VS Code : REST Client
L’extension REST Client de Huachao Mao est la solution la plus populaire pour VS Code. Installation en une commande :
code --install-extension humao.rest-client
Ou via l’interface graphique : cherchez “REST Client” dans l’onglet Extensions.
JetBrains : Support natif
Les IDE JetBrains (IntelliJ IDEA, WebStorm, PyCharm, etc.) intègrent nativement le support des fichiers .http via leur client HTTP intégré. Aucune configuration nécessaire.
Syntaxe de base
La structure minimale d’une requête est intuitive :
### Commentaire décrivant la requête
METHOD URL
Header1: value1
Header2: value2
{
"body": "content"
}
Le séparateur ### permet de définir plusieurs requêtes dans un même fichier. Chaque requête peut être exécutée indépendamment via un bouton “Send Request” qui apparaît au-dessus de la méthode HTTP.
Mise en pratique avec API.gouv.fr
La théorie étant posée, passons à la pratique avec des exemples concrets utilisant les APIs ouvertes d’API.gouv.fr. Ces APIs publiques ne nécessitent aucune authentification et offrent un terrain d’expérimentation idéal.
API Geo : données géographiques
L’API Geo (geo.api.gouv.fr) expose les données du découpage administratif français : communes, départements, régions. Commençons par une requête simple :
### Rechercher une commune par nom
GET https://geo.api.gouv.fr/communes?nom=Paris&fields=nom,code,codesPostaux,population
Exécutez cette requête (bouton “Send Request” dans VS Code, ou Ctrl+Enter dans JetBrains). La réponse JSON affiche les informations sur Paris, incluant son code INSEE, ses codes postaux et sa population.
Enrichissons avec des paramètres supplémentaires :
### Communes du département 75
GET https://geo.api.gouv.fr/departements/75/communes?fields=nom,code,population
###
### Informations sur un département spécifique
GET https://geo.api.gouv.fr/departements/75?fields=nom,code,codeRegion
Notez le séparateur ### qui permet de définir plusieurs requêtes dans le même fichier. Chacune est exécutable indépendamment.
API Adresse : géocodage d’adresses
L’API Adresse (adresse.data.gouv.fr) propose du géocodage (adresse → coordonnées) et du géocodage inverse (coordonnées → adresse).
### Géocodage d'une adresse
GET https://api-adresse.data.gouv.fr/search/?q=8 boulevard du port
###
### Géocodage avec limite de résultats
GET https://api-adresse.data.gouv.fr/search/?q=rue de la paix&limit=5
###
### Géocodage inverse (coordonnées → adresse)
GET https://api-adresse.data.gouv.fr/reverse/?lon=2.37&lat=48.357
Ces exemples illustrent la simplicité du format : pas de configuration complexe, juste des URLs et des paramètres.
Variables et environnements
Pour éviter la répétition et gérer plusieurs environnements (développement, staging, production), les fichiers .http supportent les variables.
@baseUrl = https://geo.api.gouv.fr
@department = 75
### Utilisation de variables
GET {{baseUrl}}/departements/{{department}}/communes?fields=nom,code
Les variables se définissent avec @nom = valeur et s’utilisent avec {{nom}}. Cette approche permet de centraliser les configurations et de basculer facilement entre environnements.
Gestion des secrets avec .env
Pour les APIs nécessitant une authentification, évitez d’écrire vos clés en dur. Utilisez un fichier .env :
# .env (à ajouter dans .gitignore)
API_KEY=votre_clé_secrète
API_URL=https://api.production.com
Puis référencez ces variables dans votre fichier .http :
@apiKey = {{$dotenv API_KEY}}
@baseUrl = {{$dotenv API_URL}}
### Requête authentifiée
GET {{baseUrl}}/protected-endpoint
Authorization: Bearer {{apiKey}}
La syntaxe {{$dotenv VAR_NAME}} charge automatiquement les variables depuis le fichier .env à la racine du projet.
Headers et Content-Type
Pour les requêtes POST/PUT avec un corps JSON :
### Exemple de POST (API fictive pour illustration)
POST https://api.example.com/data
Content-Type: application/json
{
"name": "Test",
"value": 42
}
Le header Content-Type informe le serveur du format du corps de la requête. Un saut de ligne sépare obligatoirement les headers du body.
Fichiers d’exemple inclus
Vous pouvez télécharger les fichiers .http prêts à l’emploi :
api-geo.http : Exemples progressifs avec l’API Geo (communes, départements, régions)
api-adresse.http : Démonstration du géocodage et géocodage inverse
api-complete.http : Exemples avancés avec variables, environnements et headers personnalisés
.env.example : Template de fichier d’environnement pour vos variables et secrets
Téléchargez ces fichiers et ouvrez-les dans VS Code ou un IDE JetBrains pour exécuter les requêtes et voir le résultat immédiatement.
Au-delà de l’IDE : automatisation et CI/CD
Les fichiers .http ne se limitent pas à une exécution manuelle depuis l’éditeur. Plusieurs outils permettent de les intégrer dans des pipelines d’automatisation.
httpyac : CLI pour fichiers .http
httpyac est un outil en ligne de commande écrit en TypeScript qui exécute des fichiers .http. Compatible avec la syntaxe de REST Client (VS Code) et du client HTTP JetBrains, il permet de transformer vos requêtes manuelles en tests automatisés.
Installation :
npm install -g httpyac
Exécution :
# Exécuter toutes les requêtes d'un fichier
httpyac send api-geo.http --all
# Exécuter avec des variables d'environnement
httpyac send api-adresse.http --all --env production
Cette approche ouvre la porte à l’intégration dans des pipelines CI/CD, permettant de valider automatiquement que vos APIs répondent correctement après chaque déploiement.
Tests d’API et couverture de code
Pour aller plus loin, httpyac peut se combiner avec des outils d’instrumentation (.NET avec dotnet-coverage, Java avec jacococli) pour mesurer la couverture de code générée par vos tests d’API. Cette technique permet de valider qu’une suite de requêtes HTTP exerce effectivement les chemins critiques de votre application sans développer des suites de tests d’intégration complexes.
L’intégration dans GitHub Actions ou Azure DevOps devient alors possible, transformant vos fichiers .http en véritables suites de tests d’intégration versionnées avec le code.
Quand utiliser les fichiers .http vs Postman
Les fichiers .http ne remplacent pas systématiquement Postman. Chaque outil a ses forces selon le contexte.
Cas d’usage privilégiés pour .http
Développement en équipe sur un projet versionné : Quand plusieurs développeurs travaillent sur une API et doivent partager des exemples de requêtes, les fichiers .http dans le repository garantissent que tout le monde utilise les mêmes tests.
Documentation technique de l’API : Un fichier .http bien commenté sert de spécification exécutable. Plus fiable qu’une documentation markdown qui peut diverger du code.
Tests d’intégration simplifiés : Avec httpyac et un pipeline CI/CD, transformez vos requêtes manuelles en tests automatisés sans framework lourd.
Projets open source : Contribuer des exemples d’utilisation sous forme de fichiers .http facilite l’onboarding des contributeurs.
Cas où Postman reste pertinent
Collaboration avec des profils non-techniques : Pour partager des requêtes avec des product managers, équipes support ou QA qui ne manipulent pas Git au quotidien, l’interface graphique de Postman élimine la barrière technique. Cliquer sur “Send” est plus accessible que maîtriser VS Code et les extensions.
Mock servers et simulation d’API : Postman permet de créer des mock servers pour simuler des APIs en développement. Cette fonctionnalité n’a pas d’équivalent direct dans l’écosystème des fichiers .http.
Documentation publique générée : La génération automatique de documentation API avec interface web interactive reste un point fort de Postman, particulièrement pour exposer une documentation publique aux consommateurs de votre API.
Approche hybride
Les deux approches ne sont pas mutuellement exclusives. Une stratégie pragmatique : utiliser Postman pour les phases d’exploration et de prototypage rapide, puis migrer les requêtes stabilisées vers des fichiers .http versionnés dans le repository. Vous bénéficiez ainsi de l’agilité de Postman en phase de découverte et de la rigueur du versionnement pour la documentation long terme.
Pour votre prochain projet d’API : .http ou pas ?
Les fichiers .http représentent une approche pragmatique du test d’API : minimaliste, versionnée, collaborative. En ramenant les requêtes HTTP directement dans votre repository, vous éliminez la friction des outils externes et créez une documentation vivante de votre API.
Pour les projets où le versionnement et la collaboration sont prioritaires, cette méthode apporte une cohérence bienvenue. Les exemples avec les APIs publiques françaises montrent qu’en quelques lignes, vous pouvez interroger des services réels sans configuration complexe.
L’écosystème autour des fichiers .http continue de mûrir avec des outils comme httpyac qui ouvrent la voie à l’automatisation. Une tendance à suivre pour qui cherche à simplifier son workflow de développement API.
Ressources pour aller plus loin
Extensions et outils :
APIs publiques françaises :
