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