Parcourir les aide-mémoire · API

Technologie: APICatégorie: Tests HTTP et APINiveau: IntermédiaireMis à jour

cURL : référence rapide

Utilisez cURL pour tester et diagnostiquer des API HTTP grâce à des modèles pratiques couvrant les méthodes, les en-têtes, l’authentification, les corps JSON, les fichiers, les redirections, les délais d’expiration, les nouvelles tentatives, l’inspection des réponses et le diagnostic sûr en production.

Sur cette page
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Requête GET simple
  5. 2. Envoyer une méthode HTTP explicite
  6. 3. Ajouter un en-tête Accept
  7. 4. Envoyer du JSON
  8. 5. Utiliser --json pour les requêtes JSON
  9. 6. Envoyer du JSON depuis un fichier
  10. 7. Envoyer les octets bruts du corps de la requête depuis un fichier
  11. 8. Ajouter un jeton Bearer
  12. 9. Authentification Basic
  13. 10. Clé d’API dans un en-tête
  14. 11. Clé d’API dans la chaîne de requête
  15. 12. Ajouter plusieurs en-têtes
  16. 13. Envoyer des paramètres de requête en toute sécurité
  17. 14. Envoyer des données de formulaire encodées en URL
  18. 15. Envoyer des données de formulaire multipart
  19. 16. Téléverser un fichier directement
  20. 17. Télécharger un fichier sous un nom précis
  21. 18. Conserver le nom de fichier fourni par le serveur
  22. 19. Suivre les redirections
  23. 20. Afficher les en-têtes et le corps de la réponse
  24. 21. Enregistrer les en-têtes de la réponse séparément
  25. 22. Afficher uniquement les en-têtes de la réponse
  26. 23. Afficher uniquement le code de statut HTTP
  27. 24. Afficher le statut et les temps
  28. 25. Afficher les temps DNS et TLS
  29. 26. Échouer sur les erreurs HTTP tout en conservant une sortie utile
  30. 27. Utiliser une sortie adaptée aux scripts
  31. 28. Définir un délai d’expiration de connexion
  32. 29. Définir un délai d’expiration global
  33. 30. Relancer les échecs transitoires
  34. 31. Être prudent avec les nouvelles tentatives de POST/PATCH/DELETE
  35. 32. Utiliser une clé d’idempotence lorsque l’API la prend en charge
  36. 33. Élargir les nouvelles tentatives uniquement si c’est justifié
  37. 34. Inspecter le détail verbeux de la requête et de la réponse
  38. 35. Ne jamais publier une sortie verbeuse sans l’avoir relue
  39. 36. Utiliser la sortie de trace pour un débogage approfondi du protocole
  40. 37. Forcer HTTP/1.1 pour comparer
  41. 38. Demander HTTP/2 lorsqu’il est pris en charge
  42. 39. Inspecter la version HTTP négociée
  43. 40. Inspecter l’IP distante
  44. 41. Remplacer la résolution DNS pour une seule requête
  45. 42. Ne modifiez pas /etc/hosts juste pour tester un endpoint
  46. 43. Définir l’en-tête Host avec prudence
  47. 44. Utiliser un proxy explicitement
  48. 45. Contourner le proxy pour certains hôtes
  49. 46. Afficher les en-têtes de la requête avec -v sans exposer les jetons
  50. 47. Envoyer des cookies
  51. 48. Enregistrer les cookies de la réponse
  52. 49. Renvoyer plus tard les cookies enregistrés
  53. 50. Envoyer un User-Agent personnalisé
  54. 51. Ajouter un identifiant de corrélation
  55. 52. Inspecter les en-têtes de limite de débit
  56. 53. Respecter Retry-After
  57. 54. Envoyer des requêtes GET conditionnelles avec ETag
  58. 55. Envoyer des requêtes conditionnelles selon la date de modification
  59. 56. Télécharger un gros fichier et reprendre le téléchargement
  60. 57. Limiter le débit de téléchargement pour des tests contrôlés
  61. 58. Annoncer la prise en charge des réponses compressées
  62. 59. Inspecter le type de contenu
  63. 60. Détecter les pages d’erreur HTML renvoyées par des proxys ou des passerelles
  64. 61. Écrire le corps et le statut séparément dans un script shell
  65. 62. Vérifier le code de sortie du processus cURL
  66. 63. Un HTTP 500 peut quand même produire le code de sortie cURL 0 sans --fail
  67. 64. Utiliser HEAD pour les seules métadonnées lorsque le serveur le prend en charge
  68. 65. Tester manuellement une requête preflight CORS
  69. 66. Tester directement un endpoint OPTIONS
  70. 67. Envoyer du JSON avec PATCH
  71. 68. Envoyer DELETE
  72. 69. Éviter de placer les secrets directement dans la ligne de commande
  73. 70. Utiliser un fichier de configuration pour les requêtes répétables
  74. 71. N’utiliser .netrc que si son modèle de sécurité convient
  75. 72. Tester la vérification TLS normalement
  76. 73. Éviter -k / --insecure comme correctif habituel
  77. 74. Utiliser un certificat d’AC personnalisé lorsque c’est approprié
  78. 75. Utiliser un certificat client lorsque mTLS est requis
  79. 76. Déboguer le nom d’hôte/TLS séparément du comportement HTTP
  80. 77. Comparer le comportement de l’API avec et sans redirections
  81. 78. Être prudent avec l’envoi d’identifiants à travers les redirections
  82. 79. Tester la taille du corps de la réponse
  83. 80. Afficher une ligne de diagnostic compacte
  84. Interpréter le résultat
  85. Points à vérifier
  86. 401 Unauthorized
  87. 403 Forbidden
  88. 404 Not Found
  89. 429 Too Many Requests
  90. 5xx
  91. Temps DNS élevé
  92. Connexion rapide mais TTFB élevé
  93. Échec TLS
  94. Notes de production
  95. cURL est un excellent outil de reproduction
  96. Protéger les secrets
  97. Les nouvelles tentatives doivent respecter l’idempotence
  98. --insecure modifie le modèle de sécurité
  99. Le diagnostic de performance nécessite plusieurs mesures de temps
  100. La syntaxe du shell varie selon l’environnement
  101. Les appels de production qui modifient l’état exigent une intention explicite
  102. Erreurs fréquentes
  103. 1. Confondre Accept et Content-Type
  104. 2. Évaluer le succès HTTP uniquement à partir du code de sortie de cURL
  105. 3. Utiliser -k pour « corriger » TLS
  106. 4. Afficher des jetons dans les journaux verbeux
  107. 5. Relancer aveuglément des requêtes POST
  108. 6. Construire manuellement des chaînes de requête sans encodage
  109. 7. Utiliser --data pour des payloads binaires
  110. 8. Supposer que HEAD se comporte exactement comme GET
  111. 9. Ignorer les redirections
  112. 10. Considérer une seule mesure de temps comme une preuve de performance
  113. Étape suivante
  114. Pour aller plus loin

Problème

Vous devez appeler ou diagnostiquer rapidement une API HTTP depuis un terminal.

Les tâches d’ingénierie typiques comprennent :

  • envoyer des requêtes GET, POST, PUT, PATCH ou DELETE
  • ajouter des en-têtes et l’authentification
  • envoyer du JSON en toute sécurité
  • téléverser ou télécharger des fichiers
  • inspecter les en-têtes de la réponse et les codes de statut
  • suivre les redirections
  • diagnostiquer des problèmes de TLS, de DNS, de délai d’expiration, de proxy ou de connectivité
  • tester les nouvelles tentatives sans dupliquer accidentellement des requêtes non sûres
  • reproduire un problème d’API en dehors de l’application

L’objectif est de rendre la requête explicite, observable et suffisamment sûre pour être utilisée lors d’un vrai diagnostic en production.

Réponse rapide

Requête de base vers une API JSON :

curl \
  --request GET \
  --url "https://api.example.com/v1/reports/123" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $API_TOKEN"

POST JSON :

curl \
  --request POST \
  --url "https://api.example.com/v1/reports" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "reportType": "sales",
    "startDate": "2026-10-01",
    "endDate": "2026-10-31"
  }'

Pour le diagnostic, commencez par :

curl \
  --silent \
  --show-error \
  --location \
  --dump-header headers.txt \
  --output body.json \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

Code / commandes

1. Requête GET simple

curl "https://api.example.com/v1/status"

À utiliser lorsque l’endpoint n’exige ni en-têtes ni authentification.


2. Envoyer une méthode HTTP explicite

curl \
  --request PATCH \
  "https://api.example.com/v1/users/123"

Utilisez --request lorsque la méthode n’est pas implicitement définie par une autre option.

Dans de nombreux cas courants :

  • --data implique POST, sauf si une autre méthode est spécifiée
  • --head effectue une requête de type HEAD
  • --upload-file utilise généralement la sémantique PUT, sauf si elle est remplacée

Être explicite améliore la lisibilité des exemples réutilisables.


3. Ajouter un en-tête Accept

curl \
  --header "Accept: application/json" \
  "https://api.example.com/v1/users/123"

Accept indique au serveur le format de réponse que le client préfère.


4. Envoyer du JSON

curl \
  --request POST \
  --url "https://api.example.com/v1/users" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Javi",
    "active": true
  }'

Content-Type décrit le corps de la requête.

Ne le confondez pas avec Accept.


5. Utiliser --json pour les requêtes JSON

Avec les versions récentes de cURL :

curl \
  --json '{
    "name": "Javi",
    "active": true
  }' \
  "https://api.example.com/v1/users"

--json est un raccourci qui envoie du JSON et définit les en-têtes JSON appropriés.

Si vous prenez en charge des environnements plus anciens, utilisez plutôt Content-Type explicite + --data.


6. Envoyer du JSON depuis un fichier

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data @payload.json \
  "https://api.example.com/v1/reports"

C’est plus sûr et plus facile à maintenir pour les corps de requête volumineux.


7. Envoyer les octets bruts du corps de la requête depuis un fichier

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @payload.json \
  "https://api.example.com/v1/reports"

Utilisez --data-binary lorsque le payload doit être envoyé sans le traitement de type formulaire appliqué par cURL.


8. Ajouter un jeton Bearer

curl \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/profile"

Préférez les variables d’environnement plutôt que de placer les secrets directement dans l’historique du shell.


9. Authentification Basic

curl \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.example.com/v1/admin"

Ne codez pas en dur les identifiants dans des scripts commités dans le contrôle de version.


10. Clé d’API dans un en-tête

curl \
  --header "X-API-Key: $API_KEY" \
  "https://api.example.com/v1/data"

Le nom de l’en-tête varie selon l’API.

Utilisez le schéma d’authentification documenté par le fournisseur.


11. Clé d’API dans la chaîne de requête

curl \
  "https://api.example.com/v1/data?api_key=$API_KEY"

Évitez ce modèle, sauf s’il est imposé.

Les secrets placés dans la chaîne de requête peuvent fuiter dans :

  • les journaux
  • l’historique du navigateur
  • les proxys
  • les systèmes de supervision

Les en-têtes sont généralement plus sûrs pour les identifiants.


12. Ajouter plusieurs en-têtes

curl \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Correlation-ID: test-123" \
  "https://api.example.com/v1/orders"

Les identifiants de corrélation sont utiles pour rapprocher la requête du client des journaux du serveur.


13. Envoyer des paramètres de requête en toute sécurité

curl \
  --get \
  --url "https://api.example.com/v1/reports" \
  --data-urlencode "merchant=ACME & Sons" \
  --data-urlencode "startDate=2026-10-01"

--data-urlencode évite les erreurs d’encodage manuel.


14. Envoyer des données de formulaire encodées en URL

curl \
  --request POST \
  --data-urlencode "username=javi" \
  --data-urlencode "scope=reports read" \
  "https://auth.example.com/token"

Cette commande envoie :

application/x-www-form-urlencoded

ce qui est courant dans les flux OAuth/d’obtention de jeton.


15. Envoyer des données de formulaire multipart

curl \
  --form "description=monthly report" \
  --form "file=@report.csv" \
  "https://api.example.com/v1/uploads"

Utilisez --form pour les téléversements multipart.


16. Téléverser un fichier directement

curl \
  --upload-file report.csv \
  "https://storage.example.com/files/report.csv"

À utiliser lorsque l’endpoint attend que le corps de la requête soit le fichier lui-même.

Vérifiez la méthode et le modèle d’authentification attendus par l’API.


17. Télécharger un fichier sous un nom précis

curl \
  --output report.csv \
  "https://api.example.com/v1/reports/123/download"

18. Conserver le nom de fichier fourni par le serveur

curl \
  --remote-name \
  "https://example.com/files/report.csv"

À utiliser uniquement si vous faites confiance à la source et au répertoire de destination.


19. Suivre les redirections

curl \
  --location \
  "https://example.com/download"

Sans --location, cURL signale normalement la réponse de redirection au lieu de la suivre.


20. Afficher les en-têtes et le corps de la réponse

curl \
  --include \
  "https://api.example.com/v1/status"

--include place les en-têtes de la réponse avant le corps dans le même flux de sortie.

Utile en mode interactif, moins pratique pour l’automatisation.


21. Enregistrer les en-têtes de la réponse séparément

curl \
  --dump-header headers.txt \
  --output body.json \
  "https://api.example.com/v1/status"

Utilisez cette option lorsque les en-têtes et le corps doivent être inspectés séparément.


22. Afficher uniquement les en-têtes de la réponse

curl \
  --head \
  "https://example.com/resource"

Cette commande demande une requête HEAD.

Sachez que toutes les API n’implémentent pas HEAD de manière pertinente.


23. Afficher uniquement le code de statut HTTP

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_code}\n" \
  "https://api.example.com/health"

Sous Windows PowerShell, /dev/null n’existe pas nativement. Utilisez une cible nulle adaptée à l’environnement ou enregistrez la réponse dans un fichier.


24. Afficher le statut et les temps

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "status=%{http_code} total=%{time_total}s connect=%{time_connect}s ttfb=%{time_starttransfer}s\n" \
  "https://api.example.com/health"

Utile pour distinguer :

  • le temps de connexion
  • le délai serveur/TTFB
  • la durée totale du transfert

Ne considérez pas une seule mesure comme un benchmark de performance.


25. Afficher les temps DNS et TLS

curl \
  --silent \
  --output /dev/null \
  --write-out \
  "dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s ttfb=%{time_starttransfer}s total=%{time_total}s\n" \
  "https://api.example.com/health"

À utiliser pour distinguer :

  • le délai DNS
  • le délai de connexion TCP
  • le délai de la négociation TLS
  • le délai applicatif/serveur

26. Échouer sur les erreurs HTTP tout en conservant une sortie utile

curl \
  --fail-with-body \
  --show-error \
  "https://api.example.com/v1/resource"

--fail-with-body renvoie un code de sortie d’échec pour les réponses d’erreur HTTP tout en conservant le corps de la réponse.

C’est généralement plus utile pour les scripts que --fail seul.

Vérifiez la version de cURL si l’option n’est pas disponible dans des environnements plus anciens.


27. Utiliser une sortie adaptée aux scripts

curl \
  --silent \
  --show-error \
  --fail-with-body \
  "https://api.example.com/v1/resource"

Cette combinaison signifie :

  • --silent : masquer l’indicateur de progression
  • --show-error : afficher quand même les erreurs cURL
  • --fail-with-body : code non nul sur les erreurs HTTP, corps conservé

28. Définir un délai d’expiration de connexion

curl \
  --connect-timeout 5 \
  "https://api.example.com/health"

Cette option limite le temps pendant lequel cURL attend l’établissement de la connexion.


29. Définir un délai d’expiration global

curl \
  --max-time 30 \
  "https://api.example.com/v1/reports/123"

Cette option limite la durée totale de la requête.

Utilisez des valeurs alignées sur la latence réellement attendue de l’API.


30. Relancer les échecs transitoires

curl \
  --retry 3 \
  --retry-delay 2 \
  --retry-max-time 30 \
  "https://api.example.com/health"

Réservez les nouvelles tentatives principalement aux opérations qui peuvent être répétées sans risque.


31. Être prudent avec les nouvelles tentatives de POST/PATCH/DELETE

Une nouvelle tentative peut dupliquer des effets de bord si l’API n’est pas idempotente.

Pour les opérations d’écriture, privilégiez :

  • les clés d’idempotence prises en charge par l’API
  • les identifiants de requête côté serveur
  • des contrats de nouvelle tentative sûrs

Ne relancez pas aveuglément les appels qui modifient l’état.


32. Utiliser une clé d’idempotence lorsque l’API la prend en charge

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data @payload.json \
  "https://api.example.com/v1/payments"

Le nom de l’en-tête et son comportement sont propres à chaque API.

N’inventez pas un mécanisme d’idempotence que le serveur ne prend pas en charge.


33. Élargir les nouvelles tentatives uniquement si c’est justifié

Les versions récentes de cURL prennent en charge :

curl \
  --retry 3 \
  --retry-all-errors \
  "https://api.example.com/health"

Cette option élargit l’ensemble des échecs qui donnent lieu à une nouvelle tentative.

Utilisez-la avec prudence, en particulier pour les requêtes qui modifient l’état.


34. Inspecter le détail verbeux de la requête et de la réponse

curl \
  --verbose \
  "https://api.example.com/v1/status"

Utile pour :

  • les en-têtes de la requête
  • les en-têtes de la réponse
  • les redirections
  • la négociation TLS
  • le comportement du proxy
  • la réutilisation des connexions

Attention : la sortie verbeuse peut exposer des identifiants.


35. Ne jamais publier une sortie verbeuse sans l’avoir relue

Les traces verbeuses peuvent contenir :

en-têtes Authorization
cookies
clés d’API
noms d’hôtes internes
jetons de session

Masquez les secrets avant de partager des journaux ou des tickets.


36. Utiliser la sortie de trace pour un débogage approfondi du protocole

curl \
  --trace-ascii trace.txt \
  "https://api.example.com/v1/status"

À utiliser uniquement si nécessaire.

Les fichiers de trace peuvent contenir des en-têtes et des corps sensibles.

Traitez-les comme des secrets tant qu’ils n’ont pas été relus.


37. Forcer HTTP/1.1 pour comparer

curl \
  --http1.1 \
  "https://api.example.com/v1/status"

À utiliser pour étudier un comportement propre à un protocole.


38. Demander HTTP/2 lorsqu’il est pris en charge

curl \
  --http2 \
  "https://api.example.com/v1/status"

La prise en charge réelle dépend de la façon dont cURL a été compilé et de ce que le serveur négocie.


39. Inspecter la version HTTP négociée

curl \
  --silent \
  --output /dev/null \
  --write-out "%{http_version}\n" \
  "https://api.example.com/v1/status"

Utile pour déboguer les différences entre HTTP/1.1 et HTTP/2.


40. Inspecter l’IP distante

curl \
  --silent \
  --output /dev/null \
  --write-out "%{remote_ip}\n" \
  "https://api.example.com/health"

Utile pour diagnostiquer le DNS, les équilibreurs de charge ou le routage régional.


41. Remplacer la résolution DNS pour une seule requête

curl \
  --resolve api.example.com:443:203.0.113.10 \
  "https://api.example.com/health"

Cette option conserve le nom d’hôte d’origine pour :

  • le SNI TLS
  • l’en-tête Host

tout en se connectant à l’IP spécifiée.

À réserver à un diagnostic contrôlé.


42. Ne modifiez pas /etc/hosts juste pour tester un endpoint

--resolve est souvent plus sûr, car il n’affecte que cette invocation de cURL.


43. Définir l’en-tête Host avec prudence

curl \
  --header "Host: api.example.com" \
  "https://203.0.113.10/health"

Cela ne remplace pas entièrement le comportement TLS fondé sur le nom d’hôte.

Pour tester HTTPS contre une IP précise, --resolve est généralement préférable.


44. Utiliser un proxy explicitement

curl \
  --proxy "http://proxy.example.com:8080" \
  "https://api.example.com/health"

Utile pour vérifier si les échecs de l’application sont liés au proxy.


45. Contourner le proxy pour certains hôtes

curl \
  --noproxy "api.example.com" \
  "https://api.example.com/health"

Vérifiez les variables d’environnement telles que :

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

lorsque cURL se comporte différemment d’une machine à l’autre.


46. Afficher les en-têtes de la requête avec -v sans exposer les jetons

Pour les appels authentifiés, envisagez de tester temporairement contre un endpoint non sensible ou de masquer les secrets dans les journaux.

N’envoyez pas de vrais jetons de production vers des sites de partage publics.


47. Envoyer des cookies

curl \
  --cookie "session_id=$SESSION_ID" \
  "https://api.example.com/profile"

À utiliser uniquement lorsque l’API s’appuie volontairement sur une authentification/un état de session par cookies.


48. Enregistrer les cookies de la réponse

curl \
  --cookie-jar cookies.txt \
  "https://api.example.com/login"

49. Renvoyer plus tard les cookies enregistrés

curl \
  --cookie cookies.txt \
  "https://api.example.com/profile"

Protégez les fichiers de cookies comme des identifiants.


50. Envoyer un User-Agent personnalisé

curl \
  --user-agent "javi-builds-api-test/1.0" \
  "https://api.example.com/health"

Utile lorsque les journaux du serveur ou les limites de débit distinguent les clients.


51. Ajouter un identifiant de corrélation

REQUEST_ID="$(uuidgen)"

curl \
  --header "X-Correlation-ID: $REQUEST_ID" \
  "https://api.example.com/v1/reports"

Le nom exact de l’en-tête dépend de l’API.

Utilisez un identifiant de requête stable pour corréler les journaux du client et du serveur.


52. Inspecter les en-têtes de limite de débit

curl \
  --include \
  "https://api.example.com/v1/data"

Recherchez des en-têtes propres à l’API, par exemple :

RateLimit-*
X-RateLimit-*
Retry-After

Les noms d’en-têtes varient selon l’implémentation.


53. Respecter Retry-After

Si le serveur renvoie :

429 Too Many Requests

avec un en-tête Retry-After, suivez cette indication au lieu de bombarder l’endpoint.


54. Envoyer des requêtes GET conditionnelles avec ETag

Inspectez d’abord :

curl \
  --include \
  "https://api.example.com/v1/config"

Si la réponse contient :

ETag: "abc123"

alors :

curl \
  --header 'If-None-Match: "abc123"' \
  "https://api.example.com/v1/config"

Un 304 Not Modified peut éviter de télécharger un contenu inchangé.


55. Envoyer des requêtes conditionnelles selon la date de modification

curl \
  --header "If-Modified-Since: Wed, 01 Oct 2026 12:00:00 GMT" \
  "https://api.example.com/v1/config"

À utiliser uniquement si le serveur prend en charge une sémantique de dernière modification pertinente.


56. Télécharger un gros fichier et reprendre le téléchargement

curl \
  --continue-at - \
  --output large-file.zip \
  "https://example.com/large-file.zip"

La reprise dépend de la prise en charge des requêtes de plage (range) par le serveur.


57. Limiter le débit de téléchargement pour des tests contrôlés

curl \
  --limit-rate 1M \
  --output file.bin \
  "https://example.com/file.bin"

Utile pour simuler des clients aux ressources limitées.


58. Annoncer la prise en charge des réponses compressées

curl \
  --compressed \
  "https://api.example.com/v1/data"

Cette option demande au serveur les encodages compressés pris en charge et décompresse automatiquement la réponse.


59. Inspecter le type de contenu

curl \
  --silent \
  --output /dev/null \
  --write-out "%{content_type}\n" \
  "https://api.example.com/v1/data"

Utile lorsqu’un endpoint renvoie de manière inattendue du HTML au lieu de JSON.


60. Détecter les pages d’erreur HTML renvoyées par des proxys ou des passerelles

Si votre client attend du JSON mais reçoit un corps HTML, inspectez :

curl \
  --include \
  "https://api.example.com/v1/data"

Examinez :

  • le code de statut
  • Content-Type
  • Server
  • les en-têtes de passerelle/proxy

L’échec peut se situer en amont de l’application.


61. Écrire le corps et le statut séparément dans un script shell

status="$(
  curl \
    --silent \
    --show-error \
    --output response.json \
    --write-out "%{http_code}" \
    "https://api.example.com/v1/data"
)"

echo "HTTP $status"

Cela permet de garder séparés le corps et le statut, lisibles par une machine.


62. Vérifier le code de sortie du processus cURL

curl \
  --fail-with-body \
  --silent \
  --show-error \
  "https://api.example.com/v1/data"

echo $?

Sur les shells POSIX :

0
→ cURL a considéré que la requête avait réussi

non nul
→ échec de transport/de protocole ou échec HTTP avec --fail*

Ne confondez pas le code de sortie de cURL avec le code de statut HTTP.


63. Un HTTP 500 peut quand même produire le code de sortie cURL 0 sans --fail

Par défaut, cURL peut transférer avec succès une réponse 500.

Si les scripts doivent échouer sur les erreurs HTTP, utilisez :

--fail-with-body

et inspectez aussi le statut HTTP.


64. Utiliser HEAD pour les seules métadonnées lorsque le serveur le prend en charge

curl --head "https://example.com/file.zip"

Utile pour :

  • la taille du contenu
  • l’ETag
  • la date de dernière modification
  • les redirections

Certaines API n’implémentent pas HEAD de manière cohérente.


65. Tester manuellement une requête preflight CORS

curl \
  --request OPTIONS \
  --header "Origin: https://app.example.com" \
  --header "Access-Control-Request-Method: POST" \
  --header "Access-Control-Request-Headers: authorization,content-type" \
  "https://api.example.com/v1/reports"

Inspectez les en-têtes de la réponse tels que :

Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers

CORS est appliqué par les navigateurs, pas par cURL lui-même.


66. Tester directement un endpoint OPTIONS

curl \
  --request OPTIONS \
  --include \
  "https://api.example.com/v1/reports"

Ne partez pas du principe que toutes les API exposent des métadonnées utiles sur les méthodes via OPTIONS.


67. Envoyer du JSON avec PATCH

curl \
  --request PATCH \
  --header "Content-Type: application/json" \
  --data '{
    "status": "disabled"
  }' \
  "https://api.example.com/v1/users/123"

Soyez prudent avec les endpoints de production qui modifient l’état.


68. Envoyer DELETE

curl \
  --request DELETE \
  --header "Authorization: Bearer $API_TOKEN" \
  "https://api.example.com/v1/users/123"

DELETE peut être destructif.

Testez hors production ou sur une ressource jetable connue, sauf si la modification est explicitement voulue.


69. Éviter de placer les secrets directement dans la ligne de commande

Risqué :

curl \
  --header "Authorization: Bearer real-secret-token" \
  ...

Les lignes de commande peuvent être conservées dans l’historique du shell ou visibles via l’inspection des processus locaux.

Préférez les variables d’environnement ou un outil de gestion sécurisée des secrets.


70. Utiliser un fichier de configuration pour les requêtes répétables

Exemple de curl.conf :

silent
show-error
fail-with-body
header = "Accept: application/json"

Puis :

curl --config curl.conf "https://api.example.com/v1/data"

Ne stockez pas de secrets dans un fichier de configuration commité.


71. N’utiliser .netrc que si son modèle de sécurité convient

cURL peut utiliser les identifiants d’un fichier .netrc.

Si vous l’utilisez :

  • restreignez les permissions du fichier
  • ne le commitez pas
  • sachez à quels hôtes il s’applique

Pour de nombreux workflows de production, une gestion dédiée des secrets est préférable.


72. Tester la vérification TLS normalement

curl "https://api.example.com/health"

Ne désactivez pas la vérification des certificats par défaut.


73. Éviter -k / --insecure comme correctif habituel

curl --insecure "https://api.example.com/health"

Cette option désactive la vérification des certificats TLS.

À utiliser uniquement pour un diagnostic contrôlé, en connaissance du risque.

N’en faites pas une habitude dans les scripts de production.


74. Utiliser un certificat d’AC personnalisé lorsque c’est approprié

curl \
  --cacert company-root-ca.pem \
  "https://internal-api.example.com/health"

Cela préserve la vérification TLS tout en faisant confiance à l’AC interne prévue.


75. Utiliser un certificat client lorsque mTLS est requis

curl \
  --cert client-cert.pem \
  --key client-key.pem \
  "https://mtls.example.com/v1/data"

Protégez les clés privées et le matériel de certificat.

Les formats et options exacts dépendent de votre build de cURL et du conditionnement des certificats.


76. Déboguer le nom d’hôte/TLS séparément du comportement HTTP

Progression utile :

résolution DNS
→ connexion TCP
→ négociation TLS
→ statut HTTP
→ corps applicatif

Utilisez les temps, --verbose et --resolve de manière ciblée pour isoler la couche en échec.


77. Comparer le comportement de l’API avec et sans redirections

Sans les suivre :

curl \
  --include \
  "https://example.com/api"

En suivant les redirections :

curl \
  --location \
  --include \
  "https://example.com/api"

Cela peut révéler des problèmes d’authentification ou de routage cachés derrière une redirection.


78. Être prudent avec l’envoi d’identifiants à travers les redirections

Lorsque les redirections changent d’hôte, comprenez comment les en-têtes d’authentification et les cookies sont traités.

Ne forcez pas la transmission des identifiants vers des hôtes sans rapport.

Vérifiez d’abord les cibles des redirections.


79. Tester la taille du corps de la réponse

curl \
  --silent \
  --output /dev/null \
  --write-out "%{size_download}\n" \
  "https://api.example.com/v1/report"

Utile lorsqu’une réponse d’API auparavant petite devient anormalement volumineuse.


80. Afficher une ligne de diagnostic compacte

curl \
  --silent \
  --show-error \
  --output response.out \
  --write-out \
  "status=%{http_code} ip=%{remote_ip} dns=%{time_namelookup}s connect=%{time_connect}s ttfb=%{time_starttransfer}s total=%{time_total}s bytes=%{size_download}\n" \
  "https://api.example.com/v1/data"

C’est utile dans les notes d’incident, car cela capture à la fois le contexte réseau et le contexte HTTP.

Interpréter le résultat

Signal Ce qu’il aide à identifier
Statut HTTP Résultat côté application/passerelle
Code de sortie cURL Succès ou échec côté client/transport/protocole
time_namelookup Durée de la résolution DNS
time_connect Temps jusqu’à l’établissement de la connexion TCP
time_appconnect Temps jusqu’à la fin de la négociation TLS
time_starttransfer Temps jusqu’au premier octet de la réponse
time_total Durée totale de la requête
remote_ip IP du serveur/de l’équilibreur de charge effectivement atteinte
content_type Représentation de la réponse renvoyée
size_download Taille du corps de la réponse
En-têtes de la réponse Indices sur le cache, la limite de débit, l’authentification, la passerelle et le traçage

Un modèle mental utile :

code de sortie cURL
→ l’opération côté client a-t-elle réussi ?

statut HTTP
→ qu’a répondu le serveur HTTP ?

corps de la réponse
→ quelle explication l’application/la passerelle a-t-elle fournie ?

Points à vérifier

401 Unauthorized

Vérifiez :

  • un jeton manquant/expiré
  • un schéma d’authentification incorrect
  • une audience/un scope incorrects
  • des problèmes d’horloge pour les jetons signés

Ne régénérez pas immédiatement les identifiants sans avoir d’abord confirmé quel identifiant la requête a réellement envoyé.

403 Forbidden

L’authentification a pu réussir alors que l’autorisation a échoué.

Vérifiez :

  • les permissions
  • le rôle/le scope
  • la politique d’accès à la ressource
  • les restrictions IP/réseau

404 Not Found

Vérifiez :

  • le chemin de l’URL
  • la version de l’API
  • l’identifiant du tenant/de la ressource
  • le routage de la passerelle
  • si le service masque volontairement les ressources non autorisées derrière un 404

429 Too Many Requests

Vérifiez :

  • Retry-After
  • les en-têtes de limite de débit
  • la concurrence des requêtes
  • les boucles de nouvelles tentatives du client

Ne relancez pas de manière agressive.

5xx

Déterminez si la réponse provient :

  • de l’application
  • de la passerelle d’API
  • du reverse proxy
  • de l’équilibreur de charge

Les en-têtes et le corps révèlent souvent quelle couche a échoué.

Temps DNS élevé

Examinez le résolveur et le chemin réseau.

Connexion rapide mais TTFB élevé

Il s’agit probablement d’un délai de traitement côté serveur/application/passerelle plutôt que de l’établissement initial de la connexion réseau.

Échec TLS

Vérifiez :

  • le nom d’hôte
  • la chaîne de certificats
  • le magasin de confiance
  • les exigences de certificat client
  • l’horloge système

Ne faites pas de --insecure une habitude.

Notes de production

cURL est un excellent outil de reproduction

Une requête cURL minimale permet de distinguer :

un bug de l’application cliente
d’un
comportement de l’API/du réseau/du serveur

Capturez la plus petite requête qui reproduit encore le problème.

Protéger les secrets

Les commandes, les traces verbeuses, l’historique du shell, les journaux de CI et les pièces jointes des tickets peuvent exposer :

  • des jetons Bearer
  • des clés d’API
  • des identifiants d’authentification Basic
  • des cookies
  • des certificats client

Masquez les secrets avant de partager.

Les nouvelles tentatives doivent respecter l’idempotence

Un GET peut généralement être relancé sans risque.

Un POST peut créer un état dupliqué, sauf si l’API fournit explicitement une sémantique d’idempotence.

--insecure modifie le modèle de sécurité

C’est un outil de diagnostic, pas un correctif de production.

Si une AC privée est attendue, configurez plutôt correctement la confiance envers cette AC.

Le diagnostic de performance nécessite plusieurs mesures de temps

Un time_total lent ne vous dit pas à lui seul si le problème vient :

  • du DNS
  • du réseau
  • de TLS
  • du traitement côté serveur
  • de la taille du téléchargement

Utilisez les champs de temps ensemble.

La syntaxe du shell varie selon l’environnement

La continuation de ligne diffère entre :

  • Bash/zsh : \
  • PowerShell : accent grave (backtick) ou splatting/tableaux
  • Windows cmd.exe : ^

Les options de cURL sont les mêmes, mais les règles de guillemets diffèrent.

Les appels de production qui modifient l’état exigent une intention explicite

Avant d’exécuter POST/PATCH/DELETE en production, confirmez :

  • l’endpoint
  • l’identifiant de la ressource
  • l’environnement
  • l’identité d’authentification
  • le payload
  • l’effet de bord attendu

Erreurs fréquentes

1. Confondre Accept et Content-Type

Accept décrit la réponse souhaitée.

Content-Type décrit le corps de la requête.

2. Évaluer le succès HTTP uniquement à partir du code de sortie de cURL

Un 500 peut quand même être un transfert réussi, sauf si --fail* est utilisé.

3. Utiliser -k pour « corriger » TLS

Cela masque les problèmes de certificat au lieu de les résoudre.

4. Afficher des jetons dans les journaux verbeux

Masquez les secrets avant de partager la sortie.

5. Relancer aveuglément des requêtes POST

Cela peut dupliquer des effets de bord.

6. Construire manuellement des chaînes de requête sans encodage

Utilisez --data-urlencode.

7. Utiliser --data pour des payloads binaires

Utilisez --data-binary ou --upload-file lorsque les octets bruts comptent.

8. Supposer que HEAD se comporte exactement comme GET

Certains services implémentent HEAD différemment, voire pas du tout.

9. Ignorer les redirections

Une redirection peut expliquer un comportement inattendu d’authentification, de passerelle ou de routage.

10. Considérer une seule mesure de temps comme une preuve de performance

Répétez des tests contrôlés et comparez-les à la télémétrie côté serveur.

Étape suivante

Utilisez l’échec observé pour choisir la prochaine investigation.

  • 401/403 → examinez l’authentification et l’autorisation.
  • 404 → vérifiez la route, la version, l’identifiant de la ressource et le routage de la passerelle.
  • 429 → examinez les en-têtes de limite de débit et le comportement du client en matière de nouvelles tentatives/concurrence.
  • 5xx → déterminez si l’erreur a été produite par l’application ou par la passerelle.
  • DNS lent → examinez le résolveur et le chemin réseau.
  • Échec TLS → vérifiez le nom d’hôte, la chaîne de certificats, la confiance et les exigences mTLS.
  • TTFB élevé → examinez l’exécution côté serveur et les dépendances.
  • Téléchargement lent mais TTFB correct → examinez la taille de la réponse et le débit réseau.
  • L’application cliente échoue mais cURL réussit → comparez les en-têtes, l’authentification, le corps, le proxy, TLS et le comportement face aux redirections.
  • Besoin d’un débogage d’API méthodique → passez à Diagnostiquer les requêtes d’API.

← Tous les aide-mémoire