Commande curl, tester une URL ou une API sans se tromper

Vous voulez vérifier si une page répond, tester un endpoint d’API ou télécharger un fichier sans ouvrir de navigateur. C’est exactement le terrain de curl. L’outil paraît austère au premier contact, parce qu’il vit dans le terminal, mais ses bases sont beaucoup plus simples qu’une longue liste d’options peut le laisser croire.

Pour bien commencer, il faut surtout comprendre une idée : curl n’est pas seulement une commande de téléchargement. C’est un outil de diagnostic réseau et un support de recette. Il permet de voir ce qu’un serveur renvoie, de reproduire une requête, de contrôler des en-têtes, de tester une authentification ou de préparer une commande qui tournera ensuite dans un script.

À quoi sert curl dans un usage réel ?

Curl envoie une requête vers une URL et affiche, enregistre ou transmet la réponse. Dans le cas le plus simple, il récupère le contenu d’une page. Dans un usage plus professionnel, il aide à comprendre pourquoi une API ne répond pas comme prévu, pourquoi une redirection boucle, pourquoi un serveur renvoie une erreur ou pourquoi un fichier ne se télécharge pas correctement. Pour un chef de projet, cette lecture évite de demander “le site est cassé” alors que la réponse montre déjà si le serveur répond, si le contenu est vide ou si la redirection absorbe la requête.

Cette approche directe explique son intérêt pour les développeurs, administrateurs système, intégrateurs, responsables QA et équipes web. Quand une interface graphique ajoute sa propre couche d’interprétation, curl permet de revenir à la base : quelle requête est envoyée et quelle réponse revient ? C’est souvent ce qu’il faut pour séparer un bug applicatif d’un problème de configuration serveur.

La commande minimale tient en une ligne. Elle envoie une requête HTTP GET vers l’URL et affiche le corps de réponse dans le terminal.

curl https://example.com

Sur une vraie page HTML, le résultat peut être très long et peu lisible. Ce n’est pas grave : à ce stade, l’objectif est de vérifier que la commande fonctionne. Ensuite, on ajoute les options utiles selon le diagnostic attendu.

Commencer par lire les en-têtes et le statut HTTP

Le premier réflexe utile consiste à demander les en-têtes de réponse. Ils indiquent notamment le statut HTTP, le type de contenu, certaines directives de cache, des redirections ou des informations serveur. Pour un audit technique, c’est plus précis que de constater qu’une page “s’affiche” dans un navigateur. Dans un audit UX, cette lecture évite de confondre une page réellement cassée avec une réponse correcte mais mal interprétée par le navigateur, un CDN ou un outil de test automatique.

curl -I https://example.com

La ligne la plus importante est souvent le statut : 200 pour une réponse OK, 301 ou 302 pour une redirection, 404 pour une ressource absente, 500 pour une erreur serveur. Ces codes ne racontent pas toute l’histoire, mais ils donnent un premier niveau de preuve. Ce code doit être lu avant le contenu, car il indique si le serveur considère la demande comme réussie, déplacée, interdite ou en erreur ; c’est souvent le raccourci le plus fiable pour orienter le diagnostic.

Si vous devez suivre une redirection jusqu’à la destination finale, ajoutez -L. C’est utile pour tester une URL raccourcie, une ancienne adresse, une redirection HTTPS ou une route d’application.

curl -L https://example.com/ancienne-page

Attention toutefois : suivre automatiquement les redirections peut masquer le chemin exact. Pour diagnostiquer une chaîne de redirections, il vaut mieux inspecter les en-têtes étape par étape ou afficher plus de détails avec le mode verbeux.

Télécharger un fichier proprement

Curl peut enregistrer une ressource dans un fichier local. L’option -o permet de choisir le nom du fichier de sortie. C’est la forme la plus lisible dans un script, parce que le nom final est explicite. En recette, ce détail évite une erreur classique : croire qu’un fichier est bien récupéré alors que la commande a seulement sauvegardé une page HTML de redirection ou d’erreur.

curl -o archive.zip https://example.com/download/archive.zip

L’option -O, elle, conserve le nom du fichier distant. Elle peut être pratique, mais elle est moins contrôlée : le nom dépend de l’URL et parfois du comportement serveur. Dans un environnement automatisé, un nom de sortie imposé évite des surprises.

curl -O https://example.com/download/archive.zip

Pour une commande destinée à un traitement récurrent, ajoutez un comportement en cas d’échec. L’option --fail demande à curl d’échouer proprement sur certaines erreurs HTTP au lieu d’enregistrer une page d’erreur comme si c’était un fichier attendu. C’est un détail important dans les scripts de sauvegarde, d’import ou de déploiement.

curl --fail -o archive.zip https://example.com/download/archive.zip

Tester une API avec une requête GET

Pour une API, le premier test consiste souvent à appeler un endpoint en GET. Curl affiche alors le JSON ou le texte renvoyé par le serveur. Si la sortie est difficile à lire, vous pouvez ensuite la transmettre à un outil comme jq, mais curl reste responsable de la requête elle-même. Cette vérification isole le serveur de l’interface : si le JSON est correct, le problème se situe peut-être dans l’affichage, le routage front ou la gestion d’état côté client.

curl https://api.example.com/users/42

Beaucoup d’API exigent des en-têtes. L’option -H permet d’en ajouter. C’est utile pour préciser le format attendu, transmettre un token d’accès ou simuler une requête proche de celle envoyée par une application.

curl -H "Accept: application/json" https://api.example.com/users/42

Avec une authentification par token, ne collez pas une vraie clé sensible dans une documentation, une capture ou un historique partagé. Utilisez une variable d’environnement dans vos scripts et remplacez la valeur dans les exemples publics. La règle est simple : un secret vu une fois doit être considéré comme compromis.

curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.example.com/users/42

Envoyer des données JSON en POST

Pour envoyer des données, on combine généralement une méthode HTTP, un en-tête de type de contenu et un corps de requête. L’option -X POST indique la méthode, -H précise le format, et -d transmet les données.

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Claire","role":"admin"}'

Dans le terminal, les guillemets comptent. Une grande partie des erreurs de débutant vient d’un JSON mal cité, surtout quand la commande est copiée entre Bash, PowerShell et un environnement CI. Si le corps devient long, utilisez un fichier JSON séparé : la commande est plus lisible et le risque d’erreur baisse.

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d @payload.json

Cette méthode est aussi plus propre pour relire, versionner et corriger le payload. Dans une équipe, c’est souvent la différence entre une commande jetable et un test reproductible.

C’est ce niveau de preuve qui compte.

Afficher les détails quand la réponse ne suffit pas

Quand une requête échoue, le corps de réponse ne suffit pas toujours. Le mode verbeux affiche davantage d’informations sur la connexion, la négociation TLS, les en-têtes envoyés et reçus, ainsi que certaines étapes réseau. C’est utile pour comprendre si le problème vient de l’URL, du certificat, du serveur, du proxy ou de l’authentification. Ce niveau de lecture aide à séparer une erreur applicative d’un blocage réseau, d’un certificat mal configuré ou d’une authentification absente, ce qui change totalement la personne à mobiliser.

curl -v https://example.com

Pour garder une trace dans un fichier, les options de trace peuvent être plus adaptées. Elles servent surtout aux diagnostics avancés, quand vous devez comparer deux environnements ou transmettre un rapport à une équipe technique.

curl --trace-ascii trace.txt https://example.com

Gardez une précaution : les traces peuvent contenir des en-têtes sensibles. Avant de les partager, relisez-les et masquez les tokens, cookies, identifiants ou paramètres privés. Un diagnostic utile ne doit pas devenir une fuite d’information.

Gérer les timeouts dans un script

Une commande curl lancée à la main peut attendre quelques secondes. Dans un script, une attente sans limite peut bloquer un traitement entier. Les options de timeout permettent de cadrer le comportement : durée maximale de connexion, durée totale de la requête, puis code de sortie exploitable par la suite du script. Pour une PME, cette différence est concrète : une recette automatique suspendue peut retarder une mise en ligne alors qu’un timeout clair aurait signalé le vrai point de blocage.

curl --connect-timeout 5 --max-time 20 \
  --fail https://api.example.com/status

Cette commande dit deux choses importantes : la connexion ne doit pas prendre plus de cinq secondes, et l’ensemble de la requête ne doit pas dépasser vingt secondes. Pour une supervision légère, un script de déploiement ou un cron, ce cadrage évite les blocages silencieux.

Ajoutez ensuite une condition shell pour réagir à l’échec. Curl renvoie un code de sortie ; vous pouvez donc arrêter le script, écrire un log ou déclencher une étape de secours.

if curl --connect-timeout 5 --max-time 20 --fail https://api.example.com/status; then
  echo "API disponible"
else
  echo "API indisponible ou réponse invalide" >&2
  exit 1
fi

Les erreurs fréquentes quand on débute avec curl

La première erreur consiste à confondre le succès de curl avec le succès métier de la requête. Une API peut répondre en HTTP 200 tout en renvoyant un message d’erreur dans le JSON. À l’inverse, une réponse HTTP 401 ou 403 peut être parfaitement normale si vous testez une route protégée sans authentification. Il faut donc lire le statut, les en-têtes et le corps.

La deuxième erreur consiste à utiliser -k trop vite. Cette option désactive la vérification du certificat TLS. Elle peut dépanner dans un environnement de test isolé, mais elle ne doit pas devenir une habitude. Si HTTPS échoue en production, la bonne réponse est de corriger le certificat, la chaîne de confiance ou la configuration, pas de masquer le problème.

La troisième erreur vient des commandes copiées sans adaptation. Une option utile dans un tutoriel peut être inutile, voire risquée, dans votre contexte. Reprenez chaque option une par une : URL, méthode, en-têtes, corps, redirections, fichier de sortie, authentification. Cette lecture lente fait gagner du temps.

Quand utiliser curl plutôt qu’un outil graphique ?

Un client API graphique reste très confortable pour explorer une documentation, organiser des collections de requêtes ou partager des scénarios avec une équipe produit. Curl n’a pas vocation à le remplacer dans tous les cas. Son avantage apparaît quand vous voulez une vérification courte, reproductible et indépendante d’une interface. Une ligne de commande se colle dans un ticket, se rejoue sur un serveur et s’intègre dans un script sans dépendre d’un poste utilisateur. Cet arbitrage compte dans les équipes hybrides : l’outil graphique aide à explorer, mais curl donne une preuve compacte que l’on peut rejouer dans un script, un ticket ou une procédure de contrôle.

Cette différence est précieuse pour les équipes web. Si un formulaire ne déclenche plus correctement un service, curl permet de tester l’endpoint directement. Si une page semble lente, il aide à distinguer la réponse serveur du rendu navigateur. Si une redirection pose problème, il donne un moyen rapide de vérifier le statut réel. Dans tous ces cas, curl sert à isoler le problème, pas à remplacer l’analyse complète.

Le bon compromis consiste souvent à documenter les requêtes importantes dans deux formats : une collection confortable pour les tests réguliers, et une commande curl courte pour les diagnostics d’urgence. Quand un incident arrive, personne n’a envie de chercher où se trouve le bon bouton. Une commande claire, déjà validée, réduit le temps de vérification.

Structurer ses commandes pour les rendre maintenables

Une commande curl d’une seule ligne est pratique pour un test rapide. Dès qu’elle contient plusieurs en-têtes, un token, un payload JSON et des options de timeout, elle devient difficile à relire. Dans ce cas, passez sur plusieurs lignes avec des antislashs en environnement Bash. Le résultat reste copiable, mais chaque option a sa place. Cette mise en forme paraît secondaire, mais elle évite les erreurs de guillemets, facilite la revue et permet de remplacer un token sans modifier le reste de la requête.

curl --fail --connect-timeout 5 --max-time 20 \
  -X POST https://api.example.com/users \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

Cette forme force aussi une lecture plus saine. Vous voyez immédiatement la méthode, l’URL, les en-têtes, le fichier envoyé et les garde-fous réseau. Pour une PME ou une équipe projet qui documente ses procédures, c’est plus utile qu’une commande compacte que personne n’ose modifier. La maintenabilité commence souvent par une commande que l’on peut relire six mois plus tard.

Dernier réflexe : ajoutez un court commentaire dans vos scripts pour expliquer l’intention, pas la syntaxe. “Vérifie que l’API de facturation répond avant l’import quotidien” est plus utile que “commande curl”. Si l’URL change, si un token expire ou si une option doit être ajustée, la personne suivante comprendra le rôle de la commande dans le flux métier.

Inutile de tout mémoriser : une petite base fiable suffit.

1. Tester d abord l URL seule avant d ajouter des options.
2. Lire le code HTTP avant d interpréter le corps de réponse.
3. Masquer les secrets avant toute capture ou partage.
4. Limiter le temps d attente dans les scripts et recettes automatisées.

Une méthode simple pour apprendre curl sans se perdre

Commencez par trois commandes : lire une URL, lire les en-têtes, télécharger un fichier. Ajoutez ensuite les requêtes API avec en-têtes et JSON. Terminez par le diagnostic : mode verbeux, traces, timeouts et codes de sortie. Cette progression évite de transformer curl en liste abstraite d’options.

Le meilleur exercice consiste à reprendre une URL que vous connaissez bien : une page de votre site, un endpoint de test ou une ressource statique. Vérifiez le statut, suivez une redirection, enregistrez la réponse, puis ajoutez un timeout. En quelques essais, vous verrez la logique : une option répond à une question précise.

Curl n’a pas besoin d’être maîtrisé en entier pour devenir utile. Si vous savez tester une URL, inspecter les en-têtes, envoyer du JSON et protéger vos commandes sensibles, vous avez déjà une base solide. La suite viendra naturellement, au fil des problèmes réels à diagnostiquer.

Pour approfondir ce point, consultez structures conditionnelles, qui traite plus précisément de bien écrire if, else et elseif dans un code lisible.