Interroger une API avec Curl
Les API RESTful sont basées sur les méthodes standards HTTP, on peut donc utiliser l'outil Curl pour interagir avec ce type d'API. Nous allons voir ici comment utiliser Curl pour créer les différentes méthodes de requête HTTP.
Syntaxe :
La syntaxe générale d'une commande Curl comporte a minima l'appel de l'exécutable curl et l'URL du serveur ciblé, et peut contenir différentes options :
curl [options] urlSyntaxe :
Les options principales sont :
-X [Méthode_HTTP]pour préciser la méthode standard à utiliser ;-H [En_tête_HTTP]pour préciser au serveur comment interpréter les données qui lui sont envoyées ;-d [Données]pour préciser les données à envoyer au serveur.
méthode GET
C'est la méthode par défaut pour Curl, on n'est donc pas obligé de la préciser.
Syntaxe :
curl -X GET url
Exemple :
Le serveur https://jsonplaceholder.typicode.com/ propose une API de test qui comportent différents articles (posts). On peut récupérer l'ensemble des articles par la commande :
curl -X GET https://jsonplaceholder.typicode.com/posts/
Ou un article spécifique, le numéro 1 par exemple, par la commande :
curl -X GET https://jsonplaceholder.typicode.com/posts/1
Remarque :
Dans les deux cas, le serveur renvoie en réponse des données JSON.
Exemple :
On peut utiliser Curl pour interroger l'API Carto module « codes postaux » :
curl -X GET https://apicarto.ign.fr/api/codes-postaux/communes/81000 | jq .
Remarque :
L'option -o permet de spécifier le nom d'un fichier dans lequel enregistrer le résultat de la requête Curl.
Exemple :
curl -o 81000.json -X GET https://apicarto.ign.fr/api/codes-postaux/communes/81000
cat 81000.json | jq .
méthode POST
La méthode POST sert à envoyer des données, il faut donc préciser le type de données envoyées dans une option -H et les données elles-mêmes avec une option -d
Syntaxe :
curl -X POST -H [En_tête_HTTP] -d [Données] url
Exemple :
curl -X POST -H 'Content-Type: application/json' -d '{"title": "foo","body": "bar","userId": 123}' https://jsonplaceholder.typicode.com/posts
Si les données sont déjà dans un fichier data.json, on peut pointer vers ce fichier avec le symbole @, et la syntaxe devient :
curl -X POST -H 'Content-Type: application/json' -d @data.json https://jsonplaceholder.typicode.com/posts
Dans les deux cas, le serveur renvoie en réponse des données JSON.
méthode PUT
La méthode PUT sert à mettre à jour des données, il faut donc préciser le type de données envoyées dans une option -H et les données elles-mêmes avec une option -d.
Syntaxe :
curl -X PUT -H [En_tête_HTTP] -d [Données] url
Exemple :
Par exemple, pour mettre à jour l'article 3 :
curl -X PUT -H 'Content-Type: application/json' -d '{"title": "foo_updated","body": "bar_updated","userId": 123}' https://jsonplaceholder.typicode.com/posts/3
Si les données sont déjà dans un fichier data.json, on peut pointer vers ce fichier avec le symbole @, et la syntaxe devient :
curl -X PUT -H 'Content-Type: application/json' -d @data.json https://jsonplaceholder.typicode.com/posts/3
Dans les deux cas, le serveur renvoie en réponse des données JSON.
méthode PATCH
La méthode PATCH sert à mettre à jour des données partiellement, il faut donc préciser le type de données envoyées dans une option -H et les données elles-mêmes avec une option -d.
Syntaxe :
curl -X PATCH -H [En_tête_HTTP] -d [Données] url
Les données à mettre à jour peuvent être dans un fichier, et la syntaxe sera alors :
curl -X PATCH -H [En_tête_HTTP] -d @[fichier_de_Données] url
Exemple :
Par exemple, pour mettre à jour l'article 1, en spécifiant un nouveau champ body :
curl -X PATCH -H 'Content-Type: application/json' -d '{"body": "nouveau contenu"}' https://jsonplaceholder.typicode.com/posts/1
méthode DELETE
La méthode DELETE sert à supprimer des données :
Syntaxe :
curl -X DELETE url
Exemple :
Par exemple, si l'on souhaite supprimer l'article 3 :
curl -X DELETE https://jsonplaceholder.typicode.com/posts/3