cURL ohne Kopfschmerzen: Komplexe Befehle in Sekunden erstellen

Wenn Sie schon länger als ein paar Monate als Entwickler tätig sind, haben Sie cURL verwendet. Sie haben wahrscheinlich auch öfter als Sie zugeben möchten nach "curl post request json" gegoogelt. Das ist keine Schande – cURL hat viele Flags, und die Syntax ist dicht genug, dass selbst erfahrene Entwickler nicht alles auswendig kennen.

Was die meisten Entwickler nicht erkennen, ist, dass Sie nur etwa ein Dutzend Flags wirklich verstehen müssen, um 90% Ihrer täglichen API-Testanforderungen abzudecken. Den Rest können Sie bei Bedarf nachschlagen oder einen Builder verwenden, um den Befehl zusammenzustellen, ohne die Syntax auswendig zu kennen.

Dieser Leitfaden konzentriert sich auf die Teile von cURL, die wirklich wichtig sind, mit realen Beispielen, die Sie heute ausführen können.

Warum überhaupt cURL?

Berechtigte Frage. Sie haben Postman, Insomnia, VS Codes REST-Client-Erweiterung, Browser-DevTools – warum cURL?

Ein paar Gründe:

Es ist immer vorhanden. cURL ist auf macOS und den meisten Linux-Systemen vorinstalliert. Auf einem frischen Server, in einem Docker-Container, auf dem Rechner eines Kollegen – cURL ist verfügbar. Postman nicht.

Es ist skriptfähig. Sie können einen cURL-Befehl in ein Bash-Skript, eine CI-Pipeline, einen Cronjob, ein Makefile einbetten. Es wird Teil Ihrer Infrastruktur. Das geht nicht mit einem GUI-Tool.

Es ist teilbar. Fügen Sie einen cURL-Befehl in eine Slack-Nachricht oder ein GitHub-Issue ein, und jeder kann ihn sofort ausführen. Keine "so erstellen Sie das in Postman nach"-Anweisungen nötig.

Es ist die gemeinsame Sprache. Die meiste API-Dokumentation zeigt cURL-Beispiele. Wenn ein Kollege sagt "hier ist die Anfrage, die fehlschlägt", schickt er oft einen cURL-Befehl. cURL lesen zu können ist eine wertvolle Fähigkeit.

Allerdings ist cURL nicht immer das richtige Tool. Komplexe mehrstufige Workflows, visuelle Antwortprüfung oder alles mit vielen Formulardaten ist oft schneller in Postman zu verwalten. Verwenden Sie das richtige Tool für die Aufgabe.

Die Flags, die Sie wirklich verwenden werden

-X — HTTP-Methode

Standardmäßig sendet cURL eine GET-Anfrage. Verwenden Sie -X, um die Methode zu ändern:

curl -X POST https://api.example.com/users
curl -X PUT https://api.example.com/users/123
curl -X DELETE https://api.example.com/users/123
curl -X PATCH https://api.example.com/users/123

Eine häufige Abkürzung: Sie können -X POST weglassen, wenn Sie -d verwenden, weil cURL POST inferiert. Aber explizit zu sein ist klarer, besonders wenn Sie den Befehl mit anderen teilen.

-H — Header hinzufügen

Fast jede API-Anfrage, die Sie stellen, benötigt mindestens einen Header. Content-Type für POST/PUT-Anfragen, Authorization für authentifizierte Endpunkte:

# Content-Type setzen
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json"

# Auth-Token hinzufügen
curl https://api.example.com/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

# Mehrere Header
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-Request-ID: abc123"

Sie können -H mehrfach im selben Befehl verwenden, ein Flag pro Header.

-d — Request-Body

Daten im Request-Body senden. Wird mit POST, PUT und PATCH verwendet:

# JSON-Body
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Formulardaten (URL-kodiert)
curl -X POST https://api.example.com/login \
  -d "username=alice&password=secret"

Ein Hinweis zum fehlenden Content-Type-Header: Wenn Sie JSON mit -d senden, aber -H "Content-Type: application/json" vergessen, lehnt der Server die Anfrage möglicherweise ab oder parst den Body falsch. Das ist einer der häufigsten cURL-Fehler. Setzen Sie immer Content-Type, wenn Sie wissen, was Sie senden.

-L — Weiterleitungen folgen

Standardmäßig stoppt cURL, wenn ein Server eine 301- oder 302-Weiterleitung zurückgibt, und zeigt die Weiterleitungsantwort. Normalerweise möchten Sie ihr folgen:

curl -L https://example.com/old-url

Das tritt häufig auf bei APIs, die HTTP auf HTTPS umleiten, oder wenn eine Ressource verschoben wurde. Ohne -L sehen Sie nur 301 Moved Permanently und fragen sich, warum Ihre Anfrage keine Daten zurückgegeben hat.

-i — Antwort-Header einbeziehen

Standardmäßig zeigt cURL nur den Antwort-Body. -i bezieht auch die Antwort-Header ein:

curl -i https://api.example.com/users/1

Die Ausgabe sieht so aus:

HTTP/2 200
content-type: application/json
x-rate-limit-remaining: 99
...

{"id": 1, "name": "Alice"}

Das ist nützlich, wenn Sie Status-Codes, Content-Type, Caching-Header oder Rate-Limit-Informationen prüfen müssen. -i ist die leichtgewichtige Alternative zum ausführlichen Modus, wenn Sie nur die Header ohne vollständige Verbindungs-Debug-Ausgabe möchten.

-v — Ausführlicher Modus

Das ist das Debug-Flag. -v zeigt alles: die vollständigen Request-Header, die cURL gesendet hat, den TLS-Handshake und die vollständigen Antwort-Header:

curl -v https://api.example.com/users

Beispielausgabe (gekürzt):

* Trying 93.184.216.34:443...
* Connected to api.example.com (93.184.216.34) port 443
* SSL connection using TLSv1.3
> GET /users HTTP/2
> Host: api.example.com
> User-Agent: curl/8.1.2
> Accept: */*
>
< HTTP/2 200
< content-type: application/json
<
{"users": [...]}

Zeilen, die mit > beginnen, sind das, was cURL gesendet hat. Zeilen mit < sind das, was der Server zurückgesendet hat. Zeilen mit * sind cURLs eigene Status-Nachrichten. Das ist unschätzbar beim Debuggen von Authentifizierungsproblemen, unerwarteten Headern oder TLS-Problemen.

-u — Basic-Authentifizierung

Für APIs mit HTTP Basic Auth könnten Sie den Authorization-Header manuell erstellen, aber -u erledigt das automatisch:

curl -u username:password https://api.example.com/protected

cURL kodiert die Anmeldedaten als Base64 und sendet den richtigen Authorization: Basic ...-Header. Ein Vorbehalt: Wenn Sie das in einem Terminal einfügen, erscheint Ihr Passwort in Ihrer Shell-Historie. Löschen Sie die Historie danach oder verwenden Sie eine Umgebungsvariable:

curl -u "alice:$API_PASSWORD" https://api.example.com/protected

-k — SSL-Verifizierung überspringen

Dieses Flag verdient ein Wort der Vorsicht. -k (oder --insecure) weist cURL an, SSL-Zertifikatfehler zu ignorieren:

curl -k https://localhost:8443/api/health

Das ist für die lokale Entwicklung legitim, wenn Sie ein selbst signiertes Zertifikat verwenden. Für Produktionsanfragen ist es nicht legitim. Wenn Sie -k gegen einen echten externen Dienst verwenden, umgehen Sie Sicherheitsmechanismen, die aus gutem Grund existieren. Verwenden Sie es nur in der Entwicklung.

-o und -O — Antwort in Datei speichern

Anstatt die Antwort im Terminal auszugeben, speichern Sie sie:

# In einem bestimmten Dateinamen speichern
curl -o output.json https://api.example.com/data

# Mit dem Remote-Dateinamen speichern
curl -O https://example.com/files/report.pdf

-o lässt Sie den Dateinamen wählen, -O verwendet das letzte Pfadsegment der URL.

-s — Stiller Modus

Unterdrückt den Fortschrittsbalken und Fehlermeldungen. Nützlich in Skripten, wo Sie nur den Antwort-Body möchten:

curl -s https://api.example.com/status | jq .

Die Weiterleitung an jq ist ein gängiges Muster für die hübsche Ausgabe von JSON-Antworten. -s hält die Ausgabe sauber, damit jq nur das JSON erhält.

Häufige Fehler

Content-Type bei POST-Anfragen vergessen

Das trifft Entwickler jedes Mal. Sie senden JSON, der Server gibt 400 Bad Request oder 415 Unsupported Media Type zurück, und Sie verbringen 20 Minuten mit Debugging, bevor Sie erkennen, dass das Fix das Hinzufügen eines Headers ist:

# Fehlender Header - Server lehnt dies möglicherweise ab
curl -X POST https://api.example.com/users \
  -d '{"name": "Alice"}'

# Korrekt
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Anführungszeichen-Probleme unter Windows

cURL unter Windows-Eingabeaufforderung behandelt Anführungszeichen anders als Bash. Einfache Anführungszeichen funktionieren in CMD nicht. Sie müssen doppelte Anführungszeichen und Escape-Zeichen für innere Anführungszeichen verwenden:

# Windows CMD - doppelte Anführungszeichen, innere escapen
curl -X POST https://api.example.com/users ^
  -H "Content-Type: application/json" ^
  -d "{\"name\": \"Alice\"}"

In PowerShell funktionieren einfache Anführungszeichen, aber die Escape-Regeln sind trotzdem anders. Das ist eine der größten Verwirrungsquellen für Windows-Entwickler, die cURL-Befehle aus für Unix-Systeme geschriebener Dokumentation verwenden. Wenn cURL-Befehle aus Dokumentation unter Windows nicht funktionieren, sind Anführungszeichen meist der Schuldige.

Datei als Body senden ohne @

Wenn Sie den Inhalt einer Datei als Request-Body senden möchten, verwenden Sie @dateiname:

# Inhalt von data.json als Body senden
curl -X POST https://api.example.com/import \
  -H "Content-Type: application/json" \
  -d @data.json

Ohne @ behandelt cURL den String als literalen Body-Wert, nicht als Dateinamen. Sie würden den literalen Text data.json statt des Dateiinhalts senden.

-d mit GET-Anfragen verwenden

-d sendet einen Body. GET-Anfragen haben keinen Body (und Server ignorieren ihn generell). Wenn Sie Query-Parameter mit einer GET-Anfrage senden möchten, fügen Sie sie in die URL ein:

# Korrekt für GET mit Parametern
curl "https://api.example.com/users?page=1&limit=20"

Beachten Sie die Anführungszeichen um die URL. Ohne sie könnte das & in der URL von Ihrer Shell als Hintergrundoperator interpretiert werden.

Zusammengesetzt: Praktische Beispiele

Benutzer erstellen:

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "Bob", "email": "bob@example.com", "role": "editor"}'

Datei hochladen:

curl -X POST https://api.example.com/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "description=Q4 Report"

(Hinweis: -F für Multipart-Formulardaten, nicht -d)

Webhook mit benutzerdefinierter Nutzlast testen:

curl -X POST https://your-app.com/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=abc123" \
  -d @sample-push-event.json

Download mit Fortschrittsanzeige:

curl -L -o large-file.zip https://example.com/downloads/archive.zip

Einen Builder statt Auswendiglernen verwenden

Für alles über eine einfache GET-Anfrage hinaus wird das Zusammenstellen der richtigen Flag-Kombination aus dem Gedächtnis mühsam. Der ToolPal cURL Command Builder ermöglicht Ihnen, Methode, URL, Header und Body über ein Formular einzugeben und generiert den cURL-Befehl für Sie – den Sie dann direkt in Ihr Terminal kopieren oder nach Bedarf anpassen können.

Das ist besonders nützlich für:

• Befehle mit Authentifizierungs-Headern erstellen, die Sie noch nie geschrieben haben
• Die Syntax für Multipart-Form-Uploads richtig hinbekommen
• Windows-kompatible Befehle generieren, wenn Sie an Bash gewöhnt sind
• Befehle mit Teamkollegen teilen, die die Flag-Syntax möglicherweise nicht kennen

Die generierten Befehle sind Standard-cURL – kein Vendor-Lock-in, nichts Proprietäres. Sie nutzen den Builder als Produktivitätsabkürzung und verwenden den resultierenden Befehl dann, wo Sie ihn benötigen.

cURL vs. andere Tools

cURL vs. Postman: Postman gewinnt bei der iterativen API-Erkundung, der Verwaltung von Anfragensammlungen und der Teamzusammenarbeit. cURL gewinnt beim Scripting, schnellen Einzelanfragen und Teilbarkeit. Sie sind keine Konkurrenten – die meisten Entwickler verwenden beide.

cURL vs. HTTPie: HTTPie ist ein neuerer Befehlszeilen-HTTP-Client mit einer freundlicheren Oberfläche und hübscherer Ausgabe. Wenn Sie bereit sind, es zu installieren, ist es einen Blick wert. cURL hat den Vorteil, ohne Installation überall verfügbar zu sein.

cURL vs. Browser-DevTools: Für die Prüfung, was Ihr Browser tatsächlich sendet (Cookies, Session-Tokens, komplexe Header), sind DevTools unübertroffen. Sie können sogar mit der rechten Maustaste auf eine Anfrage im Network-Tab klicken und sie als cURL-Befehl kopieren – eine nützliche Methode, um Browser-Anfragen über die Befehlszeile zu reproduzieren.

---

cURL belohnt die Zeit, die Sie in das Lernen investieren. Selbst wenn Sie nie alle Flags auswendig kennen, gibt Ihnen das Verstehen der Kernflags – -X, -H, -d, -L, -v – ein Tool, das überall funktioniert, leicht zu skripten ist und klar kommuniziert. Das ist mehr wert als jede Anzahl auswendig gelernter Syntaxmuster.

Im Zweifelsfall greifen Sie zu einem Builder. Wenn Sie verstehen möchten, was schiefgelaufen ist, greifen Sie zu -v.