Utiliser cURL dans ServBay

cURL est un outil en ligne de commande puissant, ainsi qu’une bibliothèque, largement utilisé pour transférer des données via différents protocoles (tels que HTTP, HTTPS, FTP, etc.). En développement web, il s’agit d’un utilitaire incontournable pour envoyer des requêtes HTTP, interroger des API, télécharger ou envoyer des fichiers, ainsi que tester des connexions à des services.

ServBay, en tant qu’environnement de développement web local conçu pour les développeurs, intègre la dernière version de cURL lors de son installation, sans qu’aucune intervention soit requise. Vous pouvez donc utiliser directement la commande curl depuis le terminal fourni par ServBay, ce qui facilite toutes sortes de tests et d’interactions réseau.

Ce guide détaille comment utiliser cURL dans l’environnement ServBay, avec des exemples pratiques et des astuces avancées.

Installation et configuration

Installation de cURL

cURL est fourni et préinstallé avec ServBay. Il n’est pas nécessaire de l’installer séparément. Vous pouvez donc exécuter la commande curl directement dans le terminal ServBay.

Pour vérifier que cURL est en place et connaître la version utilisée, tapez la commande suivante dans le terminal de ServBay :

curl --version

Cette commande affiche la version de cURL ainsi que la liste des protocoles et fonctionnalités pris en charge, confirmant que l’outil est prêt à l’emploi.

Configuration de cURL

Pour la majorité des usages courants, cURL fonctionne sans configuration supplémentaire. Son comportement peut cependant être affiné grâce à de nombreux paramètres en ligne de commande pour répondre à tous les besoins de transfert de données.

Exemples d’utilisation de base

cURL offre de nombreuses options pour réaliser toutes sortes de transferts de données. Voici quelques exemples courants illustrant comment utiliser cURL pour les opérations web fréquentes :

Envoyer une requête HTTP GET

Envoyer une requête GET est l’une des utilisations les plus répandues de cURL, notamment pour récupérer des ressources à partir d’une URL.

curl -X GET https://api.servbay.demo/data

Ou, puisque GET est la méthode par défaut, il est possible de simplifier la commande :

curl https://api.servbay.demo/data

Envoyer une requête HTTP POST

La requête POST sert habituellement à transmettre des données au serveur, par exemple des formulaires ou des charges utiles au format JSON. Utilisez l’option -d (ou --data) pour spécifier les données à envoyer.

curl -X POST -d "param1=value1&param2=value2" https://api.servbay.demo/data

Télécharger un fichier

Télécharger des fichiers avec cURL est très simple. L’option -O sauvegarde le fichier distant sous son nom d’origine dans le répertoire courant.

curl -O https://servbay.demo/file.zip

Pour choisir un nom personnalisé, utilisez l’option -o :

curl -o nom_fichier_local.zip https://servbay.demo/file.zip

Envoyer un fichier

Vous pouvez facilement simuler un envoi de fichier en ligne grâce à cURL. Utilisez l’option -F (ou --form) pour indiquer le fichier à uploader, selon le format nom=@/chemin/vers/fichier.

curl -X POST -F "file=@/Applications/ServBay/www/servbay.demo/upload/document.pdf" https://api.servbay.demo/upload

Remplacez /Applications/ServBay/www/servbay.demo/upload/document.pdf par le chemin réel du fichier à envoyer.

Astuces d’utilisation avancée

Au-delà des usages de base, cURL propose de nombreuses options avancées qui en font un outil réseau extrêmement flexible.

Définir des en-têtes HTTP personnalisés

L’option -H (ou --header) permet d’ajouter des en-têtes HTTP personnalisés à une requête. C’est très utile pour définir le type de contenu (par exemple, JSON) ou transmettre des informations d’authentification (comme une clé API ou un jeton Bearer).

curl -H "Content-Type: application/json" -H "Authorization: Bearer votre_token_ici" https://api.servbay.demo/data

Manipuler des données JSON

Le format JSON est devenu la norme pour échanger des données avec les API modernes. cURL simplifie la manipulation de ce format, qu’il s’agisse d’envoi ou de réception.

Envoyer des données JSON

Pour envoyer du JSON, il faut spécifier l’en-tête Content-Type comme application/json et utiliser l’option -d pour transmettre la chaîne JSON.

curl -X POST -H "Content-Type: application/json" -d '{"key1":"value1", "key2":"value2"}' https://api.servbay.demo/data

Lire et parser une réponse JSON (avec jq)

La réponse d’une requête cURL est brute. Pour afficher ou analyser facilement du JSON, vous pouvez combiner cURL avec jq, un puissant parseur JSON en ligne de commande.

curl -s https://api.servbay.demo/data | jq .

Remarque : jq n’est pas intégré à ServBay par défaut. Il vous faudra éventuellement l’installer séparément. Sur macOS, si Homebrew est installé, lancez : brew install jq. L’option -s de cURL active le mode silencieux (aucun affichage de progression ou d’erreurs) et s’assure que seule la réponse est transmise à jq. Pour plus d’informations, visitez le site officiel de jq.

Gérer les cookies

cURL permet d’enregistrer et de réutiliser des cookies, pratique notamment pour tester des applications web nécessitant la gestion de sessions.

Enregistrer les cookies dans un fichier

Avec l’option -c (ou --cookie-jar), vous pouvez sauvegarder les cookies envoyés par le serveur dans un fichier dédié.

curl -c cookies.txt https://servbay.demo

Réutiliser un fichier de cookies

L’option -b (ou --cookie) permet de lire un fichier de cookies et de les envoyer avec les requêtes suivantes.

curl -b cookies.txt https://servbay.demo/profile

Utiliser un proxy

Pour accéder au réseau via un proxy, spécifiez l’adresse du proxy avec l’option -x (ou --proxy).

curl -x http://proxy.servbay.demo:8080 https://api.servbay.demo/data

Limiter la bande passante de transfert

Avec l’option --limit-rate, vous pouvez fixer une limite de vitesse de transfert (en octets par seconde, ou suffixée par k/m/g). Ceci est pratique pour simuler une connexion lente ou éviter de saturer la bande passante.

curl --limit-rate 100K https://servbay.demo/largefile.zip -O

Reprise sur interruption (téléchargement à la volée)

Pour les fichiers volumineux, cURL gère la reprise sur interruption. L’option -C - permet de continuer un téléchargement interrompu à partir du point laissé.

curl -C - -O https://servbay.demo/largefile.zip

Vérifier les certificats SSL

Par défaut, cURL vérifie la validité des certificats SSL des connexions HTTPS. Pour spécifier un fichier de certificat CA particulier pour la vérification, utilisez l’option --cacert.

curl --cacert /chemin/vers/ca_personnalise.crt https://secure.servbay.demo

Si vous avez configuré un site HTTPS dans ServBay et utilisé votre propre autorité de certification fournie par ServBay (ServBay User CA ou ServBay Public CA), vous pouvez alors indiquer le bundle de certificats CA fourni par ServBay pour valider les certificats SSL locaux. Consultez la documentation SSL/HTTPS de ServBay pour obtenir l’emplacement précis du bundle CA, qui se trouve en général dans le dossier etc/ssl de l’installation de ServBay.

Avertissement : Dans certains cas de test, vous pourriez être tenté d’utiliser l’option --insecure (ou -k) pour ignorer les erreurs de validation SSL. Il est fortement déconseillé d’utiliser cette option en production ou pour manipuler des données sensibles, car elle désactive des vérifications de sécurité cruciales.

curl --insecure https://secure.servbay.demo

Foire aux questions (FAQ)

1. Message d’erreur « curl commande introuvable » dans le terminal de ServBay

• Cause : Généralement, cela signifie que le chemin du binaire ServBay n’a pas été correctement ajouté à votre environnement de terminal.
• Solution : Vérifiez que les variables d’environnement ServBay sont bien initialisées. Si le problème persiste, ouvrez ServBay, allez sur « Paramètres » > « Outils en ligne de commande », configurez séparément pour zsh et bash, puis relancez le terminal.

2. Erreur de connexion ou délai d’attente lors de l’envoi d’une requête

• Cause : Cela peut être dû à une indisponibilité du serveur distant, à un problème de réseau, à un pare-feu bloquant l’accès, ou à une erreur sur l’URL.
• Solution :
  • Vérifiez l’exactitude de l’URL saisie.
  • Assurez-vous que votre connexion réseau est opérationnelle.
  • Si vous accédez à un site ServBay local (ex : servbay.demo), vérifiez que ServBay fonctionne et que le serveur web associé (comme Caddy/Nginx) est bien actif.
  • Vérifiez si un pare-feu ou un logiciel de sécurité bloque les connexions sortantes de cURL.
  • Pour les connexions HTTPS, vérifiez la validité des certificats (voir la section sur la validation SSL).

3. Échec lors du téléchargement ou de l’envoi d’un fichier

• Cause : Mauvais chemin de fichier, droits d’accès insuffisants, opération non supportée par le serveur cible, ou erreur côté serveur.
• Solution :
  • Vérifiez l’existence et l’exactitude du chemin d’accès au fichier dans votre commande.
  • Assurez-vous que l’utilisateur exécutant ServBay ou le terminal a les droits nécessaires sur le fichier.
  • Si vous envoyez un fichier vers un site local ServBay, vérifiez la configuration du serveur pour autoriser l’upload et la présence d’un dossier cible accessible en écriture.
  • Consultez les messages d’erreur retournés par cURL pour des détails supplémentaires.

4. Échec de la validation du certificat SSL

• Cause : Certificat SSL du site cible invalide, expiré, non correspondant au domaine, chaîne de certification incomplète, ou cURL n’a pas accès au bon certificat CA.
• Solution :
  • Vérifiez la validité du certificat du site cible.
  • Si vous accédez à un site ServBay local avec un certificat signé par la CA de ServBay, suivez les instructions de cette documentation ou celle de ServBay pour spécifier le chemin du bundle de certificats avec --cacert.
  • Pour les tests rapides hors production sans données sensibles, il est possible d’ignorer la vérification (voir --insecure), mais cela reste déconseillé pour tout usage sérieux.

Conclusion

cURL est un outil en ligne de commande à la fois puissant et polyvalent, indispensable pour tout développeur web. Grâce à la version de cURL intégrée à ServBay, vous pouvez réaliser facilement tous vos tests et transferts de données en local, qu’il s’agisse de simples requêtes HTTP ou d’opérations plus complexes sur les API et les fichiers. Maîtriser les usages de base et avancés de cURL vous permettra d’accroître considérablement votre efficacité lors du développement ou du débogage.