Linux Command Line & Bash Scripting Mastery · Lektion

REST-APIs gemeinsam mit curl und jq nutzen

Verketten Sie curl-Anfragen mit jq, um Live-API-Antworten in Skripten zu extrahieren, zu paginieren und neu zu formatieren.

REST-APIs gemeinsam mit curl und jq nutzen ist eine kostenlose Linux Command Line & Bash Scripting Mastery-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Linux Command Line & Bash Scripting Mastery-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Linux Command Line & Bash Scripting Mastery-Kurs umfasst insgesamt 4 Lektionen.

Warum curl + jq die ideale Kombination ist

REST-APIs liefern JSON. curl ruft die rohe Antwort ab; jq zerlegt, filtert und formt sie um – alles in einer einzigen Pipeline. Kein Python-Skript, kein Postman und keine Zwischendatei erforderlich.

curl kümmert sich um HTTP: Methoden, Header, Authentifizierung und Weiterleitungen.
jq kümmert sich um JSON: Filtern, Zuordnen, Transformieren und Formatieren.
Durch das Zusammenführen per Pipe entstehen kompakte, kombinierbare API-Workflows.

Diese Lektion vermittelt diese Fähigkeit anhand der Grundlagen sowie praxisnaher Muster für Paginierung und Skripterstellung.

Grundlegende curl-Pipeline zu jq

Das einfachste Muster: Leiten Sie die Ausgabe von curl direkt an jq weiter. Verwenden Sie -s (silent), um die Fortschrittsanzeige von curl zu unterdrücken, sodass nur der JSON-Body jq erreicht.

-s – stiller Modus ohne Fortschrittsbalken
. – der Identitätsfilter von jq; gibt die vollständige Antwort formatiert aus
-r bei jq – Rohdatenausgabe (keine umgebenden Anführungszeichen bei Zeichenketten)

#!/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'

Anfrage-Header setzen und Authentifizierungstokens übergeben

Die meisten Produktions-APIs erfordern einen Authorization-Header oder einen API-Schlüssel. Übergeben Sie Header mit -H und speichern Sie Geheimnisse in Umgebungsvariablen – schreiben Sie sie niemals fest in den Code.

-H 'Authorization: Bearer $TOKEN' – fügt den Authentifizierungsheader ein
-H 'Accept: application/json' – fordert ausdrücklich JSON als Antwort an
Variablen werden innerhalb doppelter Anführungszeichen expandiert; verwenden Sie " um die Header-Zeichenkette

#!/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}'

Arrays filtern – .[] und select()

APIs liefern häufig Arrays zurück. Verwenden Sie .[], um jedes Element zu durchlaufen, und anschließend select(), um nur Elemente beizubehalten, die einer Bedingung entsprechen.

.[] – zerlegt ein Array in einen Stream von Objekten
select(.field == value) – behält nur passende Objekte bei
Verketten Sie mehrere Filter mit |.

#!/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'

Mehrere Felder mit map() extrahieren

map() wendet eine Transformation auf jedes Element eines Arrays an und gibt ein neues Array zurück – äquivalent zu [.[] | ...], aber besser lesbar.

map({key: .field}) – jedes Objekt umstrukturieren.
Mit @csv oder @tsv kombinieren, um tabellarische Ausgaben zu erzeugen.
Verwenden Sie -r mit @csv/@tsv, um unverarbeiteten Text zu erhalten (ohne JSON-Anführungszeichen).

#!/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'

Pagination-Muster – Schleife bis zur leeren Seite

Die meisten APIs teilen Ergebnisse in Seiten auf. Ein häufig verwendetes Muster ist eine while-Schleife, die einen Seitenzähler erhöht und beendet wird, sobald das zurückgegebene Array leer ist.

Speichern Sie die curl-Antwort mit $(curl ...) in einer Variable.
Verwenden Sie jq 'length', um zu prüfen, ob die Seite Einträge enthält.
Häufen Sie die Ergebnisse mit jq -s (Slurp) an oder hängen Sie sie an eine Datei an.

#!/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 über den Link-Header (GitHub-Stil)

GitHub und viele andere APIs verwenden einen Link-Response-Header, um die URL der nächsten Seite bereitzustellen. Sie müssen den Header parsen, statt die URL zu erraten.

curl -i nimmt Response-Header in stdout auf; alternativ können Sie mit -D - die Header nach stdout ausgeben.
Parsen Sie den Link: <url>; rel="next"-Header mit grep und sed.
Führen Sie die Schleife aus, bis kein Link mit rel="next" mehr vorhanden ist.

#!/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)"

Anfragen verketten – die Ausgabe einer Anfrage als Eingabe für eine andere verwenden

Ein häufig verwendeter Ablauf: Sie rufen eine Liste ab, extrahieren eine ID und rufen anschließend die Details für jede ID ab. Speichern Sie Zwischenwerte mit der Befehlsersetzung $() und übergeben Sie sie in der nächsten URL.

Extrahieren Sie einen einzelnen Wert mit jq -r '.field'.
Durchlaufen Sie mehrere IDs mit jq -r '.[].id' innerhalb einer while read-Schleife.
Verwenden Sie zwischen den Anfragen sleep, um Ratenbegrenzungen einzuhalten.

#!/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

POST-Anfragen – JSON-Payloads senden

Um Ressourcen zu erstellen oder zu aktualisieren, senden Sie eine POST- oder PUT-Anfrage mit einem JSON-Body. Verwenden Sie -X POST, -H 'Content-Type: application/json' und -d für den Body. Erstellen Sie den Payload mit jq -n, um Probleme mit Anführungszeichen zu vermeiden.

jq -n --arg key value '{key: $key}' – sichere Variableninterpolation in jq.
Leiten Sie das erstellte JSON direkt in curls -d @- weiter (Body von stdin lesen).
Parsen Sie die Antwort unmittelbar mit einem weiteren jq-Filter.

#!/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 '.'

Fehlerbehandlung – HTTP-Statuscodes und API-Fehler

Eine erfolgreiche HTTP-Verbindung bedeutet nicht, dass der API-Aufruf erfolgreich war. Prüfen Sie den HTTP-Statuscode und das JSON-Fehlerfeld getrennt voneinander.

curl -w '%{http_code}' hängt den Statuscode an stdout an; verwenden Sie -o, um den Body in eine Datei zu schreiben.
Vergleichen Sie den Code in Ihrem Skript und behandeln Sie 4xx- und 5xx-Fehler unterschiedlich.
Viele APIs betten {"error": "..."} in den Body ein – prüfen Sie dies mit jqs has() oder type.

#!/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"

Eine wiederverwendbare API-Hilfsfunktion erstellen

Kapseln Sie den Boilerplate-Code für curl und die Fehlerprüfung in einer Shell-Funktion. Die Funktion übernimmt Authentifizierung, Statusprüfung und JSON-Extraktion – Aufrufer müssen nur den Endpunkt und einen jq-Filter übergeben.

Geben Sie bei HTTP-Fehlern Exit-Codes ungleich null zurück, damit Aufrufer || oder set -e verwenden können.
Akzeptieren Sie ein jq-Filterargument, damit dieselbe Funktion für viele Endpunkte verwendet werden kann.
Binden Sie diese Funktionsdatei mit source in jedes Skript ein, das die API benötigt.

#!/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)>"'

Wissensüberprüfung: Pagination-Strategie

Testen Sie Ihr Verständnis dafür, wie Sie paginierte REST-API-Antworten in einem Bash-Skript mit curl und jq verarbeiten.

Lektionsrückblick: curl- und jq-API-Scripting

Sie verfügen nun über ein vollständiges Werkzeugset, um REST-APIs über die Bash-Kommandozeile zu nutzen:

Grundlegende Pipeline: curl -s URL | jq 'filter' – die Grundlage für alles Weitere.
Auth-Header: Übergeben Sie Tokens über -H aus Umgebungsvariablen, niemals fest im Code hinterlegt.
Array-Verarbeitung: .[], select() und map() filtern und strukturieren API-Antworten neu.
Pagination: Verwenden Sie eine Schleife mit Seitenzähler (leeres Array als Signal) oder parsen Sie Link-Header für APIs, die URLs der nächsten Seite bereitstellen.
Verkettung: Extrahieren Sie IDs aus einer Antwort und übergeben Sie sie innerhalb einer while read-Schleife an die nächste Anfrage.
POST mit sicheren Payloads: Erstellen Sie JSON-Bodies mit jq -n --arg und leiten Sie sie in curls -d @- weiter.
Fehlerbehandlung: Trennen Sie den HTTP-Status (-w '%{http_code}') von API-Fehlern im Body.
Wiederverwendbare Hilfsfunktion: Kapseln Sie Boilerplate-Code in einer Shell-Funktion, damit Skripte kurz und DRY bleiben.

Kombinieren Sie diese Muster, können Sie jeden JSON-API-Workflow vollständig aus der Shell heraus automatisieren – ohne zusätzliche Laufzeitumgebung.

Häufig gestellte Fragen

Ist die Lektion „REST-APIs gemeinsam mit curl und jq nutzen“ kostenlos?

Ja — der vollständige Text von „REST-APIs gemeinsam mit curl und jq nutzen“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Linux Command Line & Bash Scripting Mastery-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Linux Command Line & Bash Scripting Mastery-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „REST-APIs gemeinsam mit curl und jq nutzen“?

Verketten Sie curl-Anfragen mit jq, um Live-API-Antworten in Skripten zu extrahieren, zu paginieren und neu zu formatieren. Du übst Linux Command Line & Bash Scripting Mastery mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Linux Command Line & Bash Scripting Mastery zu starten?

Keine Vorkenntnisse erforderlich. Linux Command Line & Bash Scripting Mastery auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.

Wie lange dauert die Lektion „REST-APIs gemeinsam mit curl und jq nutzen“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Linux Command Line & Bash Scripting Mastery-Lektion Code schreiben und ausführen?

Ja. Jede Linux Command Line & Bash Scripting Mastery-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

JSON mit jq-Pipelines filtern und auswählen
JSON-Objekte mit jq umformen und erstellen
REST-APIs gemeinsam mit curl und jq nutzen
YAML-Konfigurationsdateien mit yq bearbeiten

← Zurück zu Linux Command Line & Bash Scripting Mastery