DevOps Bootcamp · Leçon

Consommer des API REST avec curl et jq

Enchaînez des requêtes curl avec jq pour extraire, paginer et reformater les réponses d’API en direct dans des scripts.

Consommer des API REST avec curl et jq est une leçon DevOps Bootcamp gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage DevOps Bootcamp, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours DevOps Bootcamp comprend 4 leçons au total.

Pourquoi curl et jq forment un duo puissant

Les API REST renvoient du JSON. curl récupère la réponse brute ; jq la découpe, la filtre et la remodèle, le tout dans une seule chaîne de traitement. Aucun script Python, aucun Postman et aucun fichier intermédiaire ne sont nécessaires.

curl gère HTTP : méthodes, en-têtes, authentification et redirections.
jq gère le JSON : filtrage, parcours, transformation et formatage.
Les relier par canalisation permet de créer des flux de travail d’API concis et composables.

Cette leçon développe cette compétence depuis les principes fondamentaux jusqu’aux schémas réels de pagination et de script.

Chaîne de traitement curl de base vers jq

Le schéma le plus simple consiste à canaliser directement la sortie de curl vers jq. Utilisez -s (silencieux) pour masquer l’indicateur de progression de curl et faire parvenir uniquement le corps JSON à jq.

-s — mode silencieux, sans barre de progression.
. — filtre d’identité de jq ; affiche joliment la réponse complète.
-r avec jq — sortie brute (sans guillemets autour des chaînes).

#!/usr/bin/env bash
# Fetch a public endpoint and pretty-print the JSON
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq '.'

# Extract just the title field as a plain string
curl -s 'https://jsonplaceholder.typicode.com/todos/1' | jq -r '.title'

Définir des en-têtes de requête et transmettre des jetons d’authentification

La plupart des API de production exigent un en-tête Authorization ou une clé d’API. Transmettez les en-têtes avec -H et stockez les secrets dans des variables d’environnement : ne les inscrivez jamais en dur.

-H 'Authorization: Bearer $TOKEN' — injecte l’en-tête d’authentification.
-H 'Accept: application/json' — demande explicitement une réponse JSON.
Les variables sont développées entre guillemets doubles ; utilisez " autour de la chaîne d’en-tête.

#!/usr/bin/env bash
TOKEN="${GITHUB_TOKEN}"   # set in your shell environment
USER="octocat"

curl -s \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/users/${USER}" \
| jq '{login: .login, repos: .public_repos, followers: .followers}'

Filtrer des tableaux — .[] et select()

Les API renvoient souvent des tableaux. Utilisez .[] pour parcourir chaque élément, puis select() pour ne conserver que les éléments correspondant à une condition.

.[] — transforme un tableau en flux d’objets.
select(.field == value) — ne conserve que les objets correspondants.
Enchaînez plusieurs filtres avec |.

#!/usr/bin/env bash
# Fetch all todos and keep only the completed ones
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true) | {id, title}]'

# Count how many are completed
curl -s 'https://jsonplaceholder.typicode.com/todos' \
| jq '[.[] | select(.completed == true)] | length'

Extraire plusieurs champs avec map()

map() applique une transformation à chaque élément d’un tableau et renvoie un nouveau tableau — équivalent à [.[] | ...], mais plus lisible.

map({key: .field}) — restructure chaque objet.
Combinez cette fonction avec @csv ou @tsv pour produire une sortie tabulaire.
Utilisez -r avec @csv/@tsv pour obtenir du texte brut (sans guillemets JSON).

#!/usr/bin/env bash
# Reshape a posts list into id + title pairs
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq 'map({id, title: .title[0:40]})'

# Output as CSV for import into a spreadsheet
curl -s 'https://jsonplaceholder.typicode.com/posts' \
| jq -r '.[] | [.id, .userId, .title] | @csv'

Modèle de pagination — boucler jusqu’à obtenir une page vide

La plupart des API paginent les résultats. Un modèle courant consiste à utiliser une boucle while qui incrémente un compteur de pages et s’arrête lorsque le tableau renvoyé est vide.

Stockez la réponse de curl dans une variable avec $(curl ...).
Utilisez jq 'length' pour vérifier si la page contient des éléments.
Accumulez les résultats avec jq -s (rassemblement) ou ajoutez-les à un fichier.

#!/usr/bin/env bash
# Paginate through jsonplaceholder posts (simulated: page stops at page 2
# because the API returns the full list regardless of ?_page, but the
# pattern is correct for real paginated APIs)

PAGE=1
PER_PAGE=10
OUTPUT="all_posts.json"
echo '[]' > "$OUTPUT"

while true; do
  RESPONSE=$(curl -s "https://jsonplaceholder.typicode.com/posts?_page=${PAGE}&_limit=${PER_PAGE}")
  COUNT=$(echo "$RESPONSE" | jq 'length')

  if [ "$COUNT" -eq 0 ]; then
    echo "No more pages. Stopping at page $((PAGE - 1))."
    break
  fi

  # Merge new items into the accumulated JSON array
  CURRENT=$(cat "$OUTPUT")
  echo "$CURRENT" "$RESPONSE" | jq -s '.[0] + .[1]' > "$OUTPUT"
  echo "Page $PAGE: fetched $COUNT items."
  PAGE=$((PAGE + 1))
done

echo "Total collected: $(jq 'length' "$OUTPUT")"

Pagination avec l’en-tête Link (style GitHub)

GitHub et de nombreuses autres API utilisent un en-tête de réponse Link pour fournir l’URL de la page suivante. Vous devez analyser l’en-tête plutôt que deviner l’URL.

curl -i inclut les en-têtes de réponse dans la sortie standard ; vous pouvez aussi utiliser -D - pour les afficher dans la sortie standard.
Analysez l’en-tête Link: <url>; rel="next" avec grep et sed.
Bouclez jusqu’à ce qu’aucun lien rel="next" ne soit présent.

#!/usr/bin/env bash
# Follow Link-header pagination (GitHub repos example)
# Requires GITHUB_TOKEN in environment
TOKEN="${GITHUB_TOKEN}"
NEXT_URL="https://api.github.com/users/torvalds/repos?per_page=5"
ALL_REPOS="[]"

while [ -n "$NEXT_URL" ]; do
  # Capture full response (headers + body) to a temp file
  TMPFILE=$(mktemp)
  curl -sD "$TMPFILE" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "$NEXT_URL" \
  | {
      BODY=$(cat)
      ALL_REPOS=$(echo "$ALL_REPOS" "$BODY" | jq -s '.[0] + .[1]')
      echo "$ALL_REPOS" > /tmp/repos_acc.json
    }

  # Extract next URL from Link header
  NEXT_URL=$(grep -i '^link:' "$TMPFILE" \
    | sed -E 's/.*<([^>]+)>; rel="next".*/\1/;t;d')
  rm -f "$TMPFILE"
done

echo "Total repos: $(jq 'length' /tmp/repos_acc.json)"

Enchaîner les requêtes — utiliser la sortie d’un appel comme entrée d’un autre

Flux de travail courant : récupérez une liste, extrayez un ID, puis récupérez le détail correspondant à chaque ID. Stockez les valeurs intermédiaires avec la substitution de commande $() et transmettez-les à l’URL suivante.

Extrayez une valeur unique avec jq -r '.field'.
Parcourez plusieurs ID avec jq -r '.[].id' dans une boucle while read.
Utilisez sleep entre les requêtes pour respecter les limites de fréquence.

#!/usr/bin/env bash
# Step 1: get all user IDs from the /users endpoint
# Step 2: for each user, fetch their posts and count them

curl -s 'https://jsonplaceholder.typicode.com/users' \
| jq -r '.[].id' \
| while read -r USER_ID; do
    POST_COUNT=$(curl -s "https://jsonplaceholder.typicode.com/posts?userId=${USER_ID}" \
                 | jq 'length')
    echo "User ${USER_ID}: ${POST_COUNT} posts"
    sleep 0.1   # be polite to the API
done

Requêtes POST — envoyer des charges JSON

Pour créer ou mettre à jour des ressources, envoyez une requête POST ou PUT avec un corps JSON. Utilisez -X POST, -H 'Content-Type: application/json' et -d pour le corps. Construisez la charge utile avec jq -n afin d’éviter les problèmes liés aux guillemets.

jq -n --arg key value '{key: $key}' — interpolation sûre d’une variable dans jq.
Transmettez directement le JSON construit à l’option -d @- de curl (lecture du corps depuis l’entrée standard).
Analysez immédiatement la réponse avec un autre filtre jq.

#!/usr/bin/env bash
TITLE="My New Post"
BODY_TEXT="Written via curl and jq."
USER_ID=1

# Build the JSON payload safely and POST it
RESPONSE=$(jq -n \
  --arg title   "$TITLE" \
  --arg body    "$BODY_TEXT" \
  --argjson userId "$USER_ID" \
  '{title: $title, body: $body, userId: $userId}' \
| curl -s \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    'https://jsonplaceholder.typicode.com/posts')

echo "Created post ID: $(echo "$RESPONSE" | jq '.id')"
echo "Full response:"
echo "$RESPONSE" | jq '.'

Gestion des erreurs — codes d’état HTTP et erreurs d’API

Une connexion HTTP réussie ne signifie pas que l’appel à l’API a abouti. Vérifiez séparément le code d’état HTTP et le champ d’erreur JSON.

curl -w '%{http_code}' ajoute le code d’état à la sortie standard ; utilisez -o pour écrire le corps dans un fichier.
Comparez le code dans votre script et gérez différemment les erreurs 4xx et 5xx.
De nombreuses API intègrent {"error": "..."} dans le corps — vérifiez-le avec has() ou type de jq.

#!/usr/bin/env bash
API_URL='https://jsonplaceholder.typicode.com/todos/99999'
TMPBODY=$(mktemp)

HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' "$API_URL")

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
  echo "Success ($HTTP_CODE):"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -eq 404 ]; then
  echo "Resource not found (404). Body:"
  jq '.' "$TMPBODY"
elif [ "$HTTP_CODE" -ge 500 ]; then
  echo "Server error ($HTTP_CODE). Retrying later."
else
  echo "Unexpected status: $HTTP_CODE"
  cat "$TMPBODY"
fi

rm -f "$TMPBODY"

Créer une fonction réutilisable d’aide pour les API

Regroupez le code répétitif de curl et de vérification des erreurs dans une fonction d’interpréteur de commandes. La fonction gère l’authentification, la vérification de l’état et l’extraction JSON ; les appelants lui transmettent simplement le point de terminaison et un filtre jq.

Renvoyez des codes de sortie non nuls en cas d’erreur HTTP afin que les appelants puissent utiliser || ou set -e.
Acceptez un argument correspondant au filtre jq afin que la même fonction serve pour de nombreux points de terminaison.
Chargez ce fichier de fonction depuis tout script qui a besoin de l’API.

#!/usr/bin/env bash
# api_get <endpoint_path> <jq_filter>
# Returns filtered JSON or exits non-zero on error.
api_get() {
  local PATH_PART="$1"
  local JQ_FILTER="${2:-.}"
  local BASE_URL='https://jsonplaceholder.typicode.com'
  local TMPBODY
  TMPBODY=$(mktemp)

  local HTTP_CODE
  HTTP_CODE=$(curl -s \
    -o "$TMPBODY" \
    -w '%{http_code}' \
    "${BASE_URL}${PATH_PART}")

  if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
    echo "[ERROR] HTTP $HTTP_CODE for ${PATH_PART}" >&2
    rm -f "$TMPBODY"
    return 1
  fi

  jq -r "$JQ_FILTER" "$TMPBODY"
  rm -f "$TMPBODY"
}

# Usage examples
api_get '/todos/1' '.title'
api_get '/posts?userId=1' '[.[] | .title]'
api_get '/users' '.[] | "\(.id) \(.name) <\(.email)>"'

Vérification des connaissances : stratégie de pagination

Vérifiez votre compréhension de la gestion des réponses paginées d’une API REST dans un script Bash utilisant curl et jq.

Récapitulatif de la leçon : scripts d’API avec curl et jq

Vous disposez maintenant d’une boîte à outils complète pour exploiter les API REST depuis la ligne de commande Bash :

Chaîne de traitement de base : curl -s URL | jq 'filter' — le fondement de tout le reste.
En-têtes d’authentification : transmettez les jetons via -H à partir de variables d’environnement, jamais en les inscrivant directement dans le code.
Gestion des tableaux : .[], select() et map() permettent d’extraire et de restructurer les réponses d’API.
Pagination : bouclez avec un compteur de pages (sentinelle correspondant à un tableau vide) ou analysez les en-têtes Link pour les API fournissant l’URL suivante de cette manière.
Enchaînement : extrayez les ID d’une réponse et transmettez-les à la requête suivante dans une boucle while read.
POST avec des charges sûres : construisez les corps JSON avec jq -n --arg et transmettez-les à l’option -d @- de curl.
Gestion des erreurs : séparez l’état HTTP (-w '%{http_code}') des erreurs propres à l’API présentes dans le corps.
Fonction d’aide réutilisable : regroupez le code répétitif dans une fonction d’interpréteur de commandes afin que les scripts restent concis et respectent le principe DRY.

Combinez ces modèles et vous pourrez automatiser entièrement depuis l’interpréteur de commandes n’importe quel flux de travail avec une API JSON — sans environnement d’exécution supplémentaire.

Questions Fréquemment Posées

La leçon « Consommer des API REST avec curl et jq » est-elle gratuite ?

Oui — le texte complet de « Consommer des API REST avec curl et jq » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours DevOps Bootcamp, passe à CoddyKit PRO. Le cours DevOps Bootcamp comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Consommer des API REST avec curl et jq » ?

Enchaînez des requêtes curl avec jq pour extraire, paginer et reformater les réponses d’API en direct dans des scripts. Tu pratiques DevOps Bootcamp avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer DevOps Bootcamp ?

Aucune expérience préalable n'est requise. DevOps Bootcamp sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « Consommer des API REST avec curl et jq » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon DevOps Bootcamp ?

Oui. Chaque leçon DevOps Bootcamp inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Filtrer et sélectionner du JSON avec les pipelines jq
Transformer et construire des objets JSON avec jq
Consommer des API REST avec curl et jq
Modifier des fichiers de configuration YAML avec yq

← Retour à DevOps Bootcamp