cURL sans prise de tête : construisez des commandes complexes en quelques secondes

Si vous êtes développeur depuis plus de quelques mois, vous avez utilisé cURL. Vous avez probablement aussi googé "curl post request json" plus souvent que vous ne voudriez l'admettre. Il n'y a pas de honte à ça — cURL a beaucoup de flags, et la syntaxe est suffisamment dense pour que même les développeurs expérimentés ne gardent pas tout en mémoire.

Ce que la plupart des développeurs ne réalisent pas, c'est que vous n'avez besoin de comprendre profondément qu'une douzaine de flags pour couvrir 90% de vos besoins quotidiens de tests API. Le reste, vous pouvez le chercher quand vous en avez besoin, ou utiliser un constructeur pour assembler la commande sans mémoriser la syntaxe.

Ce guide se concentre sur les parties de cURL qui comptent vraiment, avec des exemples réels que vous pouvez exécuter aujourd'hui.

Pourquoi cURL du tout?

Question légitime. Vous avez Postman, Insomnia, l'extension REST Client de VS Code, les DevTools du navigateur — pourquoi cURL?

Quelques raisons :

Il est toujours là. cURL est préinstallé sur macOS et la plupart des systèmes Linux. Sur un serveur fraîchement installé, dans un conteneur Docker, sur la machine d'un collègue — cURL est disponible. Postman ne l'est pas.

Il est scriptable. Vous pouvez mettre une commande cURL dans un script bash, un pipeline CI, une tâche cron, un Makefile. Elle devient partie de votre infrastructure. Vous ne pouvez pas faire ça avec un outil GUI.

Il est partageable. Collez une commande cURL dans un message Slack ou un ticket GitHub et n'importe qui peut l'exécuter immédiatement. Pas d'instructions "voici comment reproduire ça dans Postman" nécessaires.

C'est le langage commun. La plupart des documentations API montrent des exemples cURL. Quand un collègue dit "voici la requête qui échoue", il enverra souvent une commande cURL. Savoir lire cURL est une compétence qui vaut la peine d'avoir.

Cela dit, cURL n'est pas toujours le bon outil. Les flux de travail multi-étapes complexes, l'inspection visuelle des réponses, ou tout ce qui implique beaucoup de données de formulaire est souvent plus rapide à gérer dans Postman. Utilisez le bon outil pour le travail.

Les flags que vous utiliserez vraiment

-X — Méthode HTTP

Par défaut, cURL envoie une requête GET. Utilisez -X pour changer la méthode :

curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123
curl -X PATCH https://api.example.com/users/123

Un raccourci courant : vous pouvez sauter -X POST quand vous utilisez -d pour envoyer un corps, car cURL inférera POST. Mais être explicite est plus clair, surtout quand vous partagez la commande avec d'autres.

-H — Ajouter un header

Presque toutes les requêtes API que vous ferez auront besoin d'au moins un header. Content-Type pour les requêtes POST/PUT, Authorization pour les endpoints authentifiés :

# Définir le type de contenu
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json"

# Ajouter un token d'auth
curl https://api.example.com/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Plusieurs headers
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Request-ID: abc123"

Vous pouvez utiliser -H plusieurs fois dans la même commande, un flag par header.

-d — Corps de requête

Envoyer des données dans le corps de la requête. Utilisé avec POST, PUT et PATCH :

# Corps JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Données de formulaire (encodées en URL)
curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret"

Une note sur le header Content-Type manquant : si vous envoyez -d avec du JSON mais oubliez -H "Content-Type: application/json", le serveur peut rejeter la requête ou mal analyser le corps. C'est l'une des erreurs cURL les plus courantes. Définissez toujours Content-Type quand vous savez ce que vous envoyez.

-L — Suivre les redirections

Par défaut, si un serveur renvoie une redirection 301 ou 302, cURL s'arrête et affiche la réponse de redirection. Généralement vous voulez la suivre :

curl -L https://example.com/old-url

Cela arrive souvent quand on travaille avec des API qui redirigent HTTP vers HTTPS, ou quand une ressource a été déplacée. Sans -L, vous verrez juste 301 Moved Permanently et vous vous demanderez pourquoi votre requête n'a renvoyé aucune donnée.

-i — Inclure les headers de réponse

Par défaut, cURL ne montre que le corps de la réponse. -i inclut également les headers de réponse :

curl -i https://api.example.com/users/1

La sortie ressemble à :

HTTP/2 200
content-type: application/json
x-rate-limit-remaining: 99
...

{"id": 1, "name": "Alice"}

C'est utile quand vous devez inspecter les codes de statut, Content-Type, les headers de cache ou les informations de limite de taux. -i est l'alternative légère au mode verbose quand vous voulez juste les headers sans toute la sortie de debug de connexion.

-v — Mode verbose

C'est le flag de débogage. -v vous montre tout : les headers de requête complets que cURL a envoyés, le handshake TLS et les headers de réponse complets :

curl -v https://api.example.com/users

Exemple de sortie (abrégé) :

* Trying 93.184.216.34:443...
* Connected to api.example.com (93.184.216.34) port 443
* SSL connection using TLSv1.3
> GET /users HTTP/2
> Host: api.example.com
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"users": [...]}

Les lignes commençant par > sont ce que cURL a envoyé. Les lignes commençant par < sont ce que le serveur a renvoyé. Les lignes commençant par * sont les messages de statut de cURL. Inestimable pour déboguer les problèmes d'authentification, les headers inattendus ou les problèmes TLS.

-u — Authentification basique

Pour les API utilisant HTTP Basic Auth, vous pourriez construire manuellement le header Authorization, mais -u le fait automatiquement :

curl -u username:password https://api.example.com/protected

cURL encode les identifiants en Base64 et envoie le header Authorization: Basic ... approprié. Un avertissement : si vous collez ça dans un terminal, votre mot de passe apparaîtra dans votre historique shell. Videz l'historique ensuite, ou utilisez une variable d'environnement :

curl -u "alice:$API_PASSWORD" https://api.example.com/protected

-k — Ignorer la vérification SSL

Celui-ci mérite une mise en garde. -k (ou --insecure) dit à cURL d'ignorer les erreurs de certificat SSL :

curl -k https://localhost:8443/api/health

C'est légitime pour le développement local quand vous utilisez un certificat auto-signé. Ce n'est pas légitime pour les requêtes de production. Si vous utilisez -k contre un vrai service externe, vous contournez une sécurité qui existe pour de bonnes raisons. Utilisez-le uniquement en développement.

-o et -O — Sauvegarder la réponse dans un fichier

Au lieu d'imprimer la réponse dans votre terminal, sauvegardez-la :

# Sauvegarder sous un nom de fichier spécifique
curl -o output.json https://api.example.com/data

# Sauvegarder avec le nom de fichier distant
curl -O https://example.com/files/report.pdf

-o vous laisse choisir le nom de fichier, -O utilise le dernier segment de chemin de l'URL.

-s — Mode silencieux

Supprime la barre de progression et les messages d'erreur. Utile dans les scripts où vous voulez seulement le corps de la réponse :

curl -s https://api.example.com/status | jq .

Passer à jq est un modèle courant pour formater joliment les réponses JSON. -s garde la sortie propre pour que jq ne reçoive que le JSON.

Erreurs courantes

Oublier Content-Type sur les requêtes POST

Ça attrape les développeurs à chaque fois. Vous envoyez du JSON, le serveur renvoie 400 Bad Request ou 415 Unsupported Media Type, et vous passez 20 minutes à déboguer avant de réaliser que la correction est d'ajouter un header :

# Header manquant - le serveur peut rejeter ça
curl -X POST https://api.example.com/users \
  -d '{"name": "Alice"}'

# Correct
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Problèmes de guillemets sous Windows

cURL sous l'invite de commandes Windows gère les guillemets différemment de bash. Les guillemets simples ne fonctionnent pas dans CMD. Vous devez utiliser des guillemets doubles et échapper les guillemets internes :

# Windows CMD - guillemets doubles, échapper les guillemets internes
curl -X POST https://api.example.com/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\": \"Alice\"}"

Dans PowerShell, les guillemets simples fonctionnent mais les règles d'échappement sont toujours différentes. C'est l'une des plus grandes sources de confusion pour les développeurs Windows utilisant des commandes cURL de documentation écrite pour les systèmes Unix. Si vous êtes sous Windows et que les commandes cURL de la documentation ne fonctionnent pas, les guillemets sont généralement le coupable.

Envoyer un fichier comme corps sans utiliser @

Quand vous voulez envoyer le contenu d'un fichier comme corps de requête, vous utilisez @nomdefichier :

# Envoyer le contenu de data.json comme corps
curl -X POST https://api.example.com/import \
  -H "Content-Type: application/json" \
  -d @data.json

Sans @, cURL traite la chaîne comme une valeur de corps littérale, pas comme un nom de fichier. Vous enverriez le texte littéral data.json au lieu du contenu du fichier.

Utiliser -d avec des requêtes GET

-d envoie un corps. Les requêtes GET n'ont pas de corps (et les serveurs l'ignorent généralement). Si vous voulez envoyer des paramètres de requête avec une requête GET, mettez-les dans l'URL :

# Correct pour GET avec paramètres
curl "https://api.example.com/users?page=1&limit=20"

Notez les guillemets autour de l'URL. Sans eux, le & dans l'URL pourrait être interprété par votre shell comme un opérateur d'arrière-plan.

Tout mettre ensemble : exemples réels

Créer un utilisateur :

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Bob", "email": "bob@example.com", "role": "editor"}'

Téléverser un fichier :

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "description=Q4 Report"

(Note : -F pour les données de formulaire multipart, pas -d)

Vérifier un webhook avec une charge utile personnalisée :

curl -X POST https://your-app.com/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=abc123" \
  -d @sample-push-event.json

Télécharger avec progression :

curl -L -o large-file.zip https://example.com/downloads/archive.zip

Utiliser un constructeur plutôt que mémoriser

Pour tout ce qui dépasse une requête GET basique, assembler la bonne combinaison de flags de mémoire devient fastidieux. Le constructeur de commandes cURL ToolPal vous permet de remplir la méthode, l'URL, les headers et le corps via un formulaire et génère la commande cURL pour vous — que vous pouvez alors copier directement dans votre terminal ou adapter selon vos besoins.

C'est particulièrement utile pour :

• Construire des commandes avec des headers d'authentification que vous n'avez jamais écrits
• Obtenir la bonne syntaxe pour les téléversements de formulaires multipart
• Générer des commandes compatibles Windows quand vous êtes habitué à bash
• Partager des commandes avec des coéquipiers qui pourraient ne pas connaître la syntaxe des flags

Les commandes générées sont du cURL standard — pas de verrouillage fournisseur, rien de propriétaire. Vous utilisez le constructeur comme raccourci de productivité, puis vous prenez la commande résultante où vous en avez besoin.

cURL vs autres outils

cURL vs Postman : Postman gagne pour l'exploration API itérative, la gestion des collections de requêtes et la collaboration en équipe. cURL gagne pour les scripts, les requêtes rapides ponctuelles et le partage. Ils ne sont pas concurrents — la plupart des développeurs utilisent les deux.

cURL vs HTTPie : HTTPie est un client HTTP en ligne de commande plus récent avec une interface plus conviviale et une sortie plus jolie. Si vous êtes prêt à l'installer, cela vaut le coup d'oeil. cURL a l'avantage d'être disponible partout sans installation.

cURL vs DevTools du navigateur : Pour inspecter ce que votre navigateur envoie réellement (cookies, tokens de session, headers complexes), DevTools est imbattable. Vous pouvez même faire un clic droit sur une requête dans l'onglet Network et la copier comme commande cURL — un moyen utile de reproduire des requêtes de navigateur depuis la ligne de commande.

---

cURL récompense le temps que vous investissez à l'apprendre. Même si vous ne mémorisez jamais tous les flags, comprendre comment les flags principaux fonctionnent — -X, -H, -d, -L, -v — vous donne un outil qui fonctionne partout, se script facilement et communique clairement. Cela vaut plus que n'importe quel nombre de modèles de syntaxe mémorisés.

Dans le doute, utilisez un constructeur. Quand vous avez besoin de comprendre ce qui a mal tourné, utilisez -v.