curl POST-Anfrage: JSON, Header und Formulardaten senden

Veröffentlicht:

14 Min. Lesezeit

Acar Diveroli
Autor: Acar Diveroli
Terminalfenster mit einem curl-POST-Befehl, der Teil --json in Blau, dahinter eine Antwortkarte mit 201 Created

Die Dokumentation einer API zeigt einen einzeiligen curl-Befehl, der eine Bestellung anlegt. Sie fügen ihn ein, ergänzen Ihren Schlüssel, drücken Enter, und der Server antwortet mit 415 Unsupported Media Type oder mit 400 und invalid JSON, obwohl das JSON korrekt aussieht. Auf dem Linux-Laptop eines Kollegen funktioniert dieselbe Zeile. Mit der API ist alles in Ordnung: Der Befehl hat einen anderen Body oder einen anderen Content-Type gesendet, als Sie denken, und unter Windows hat die Shell die Anführungszeichen aus Ihrem JSON entfernt, bevor curl es überhaupt gesehen hat.

Dieser Artikel behandelt Formulardaten mit -d, JSON mit --json oder -H plus -d, Bodys aus Dateien, Uploads mit -F, Header und Authentifizierung, die Frage, wann -X POST nötig ist, das Lesen der Antwort und das Setzen von Anführungszeichen in cmd und PowerShell. Jeder Befehl lief mit curl 8.22.0 unter Windows 11, in cmd und in Windows PowerShell 5.1, gegen einen kleinen Echo-Server auf unserem eigenen Rechner, der Methode, Content-Type-Header und empfangenen Body ausgab.

Was ist eine POST-Anfrage?

Eine POST-Anfrage ist eine HTTP-Anfrage, die Daten in ihrem Body transportiert und den Server bittet, etwas damit zu tun: eine Bestellung anlegen, ein Formular speichern, einen Job starten. RFC 9110, der HTTP-Standard, definiert POST als Aufforderung an die Zielressource, die im Body enthaltene Darstellung zu verarbeiten, und zwar nach ihren eigenen Regeln.

GET fragt nur etwas ab und hat keinen Body. POST ist außerdem nicht idempotent: Derselbe POST, zweimal gesendet, kann zwei Bestellungen anlegen. Wenn Anfragen, Endpoints und Statuscodes neu für Sie sind, beginnen Sie mit Was ist eine API und wie funktioniert sie?.

Zwei Teile eines POST zählen am meisten. Der Body sind die Daten. Der Header Content-Type sagt dem Server, wie er sie lesen soll: als Formularfelder, als JSON oder als Multipart-Upload. Die meisten Probleme mit curl-POST-Anfragen sind ein Widerspruch zwischen beiden.

Wie sendet curl eine POST-Anfrage?

curl wechselt von selbst zu POST, wenn Sie eine Body-Option angeben; Sie beschreiben die Daten, curl leitet die Methode daraus ab:

  1. Sie ergänzen eine Body-Option. -d, --data-binary, --data-urlencode, --json oder -F macht die Anfrage zum POST.
  2. curl wählt einen Content-Type. Die -d-Familie sendet application/x-www-form-urlencoded, --json sendet application/json, -F sendet multipart/form-data mit einer Boundary.
  3. curl bereitet den Body vor. Mehrere -d-Teile verbindet es mit &, aus Dateien, die per -d @ gelesen werden, entfernt es die Zeilenumbrüche, und mit --data-binary und --json bleiben Dateien unverändert.
  4. curl sendet die Anfrage. POST /orders HTTP/1.1, die Header einschließlich Content-Length, Content-Type und Ihrer -H-Werte, danach der Body.
  5. Der Server liest zuerst Content-Type. Eine JSON-API, die als Formular gekennzeichnete Daten erhält, lehnt sie mit 415 ab oder scheitert mit 400 am Parsen.
  6. curl gibt den Body der Antwort aus. Status und Header bleiben verborgen, solange Sie nicht mit -i, -v oder -w danach fragen.

Welche curl-Option passt für den Body der Anfrage?

Wählen Sie die Option, die zu dem passt, was der Server erwartet. Das kam bei unserem Echo-Server jeweils an:

OptionGesendeter Content-TypeUmgang mit dem BodyEinsatz
-d / --dataapplication/x-www-form-urlencodedWie getippt; @file verliert ZeilenumbrücheFormulare wie im Browser
--data-urlencodeapplication/x-www-form-urlencodedWert per Prozentkodierung kodiertWerte mit Leerzeichen oder &
--data-binaryapplication/x-www-form-urlencodedByte für ByteDateien, die exakt bleiben müssen
--jsonapplication/jsonByte für Byte, ergänzt AcceptJSON-APIs (ab 7.82.0)
-F / --formmultipart/form-dataIn benannte Teile zerlegtDatei-Uploads

Alle sind in der curl-Manpage beschrieben, der Referenz für jede Option in diesem Artikel.

Wie senden Sie Formulardaten mit -d?

-d sendet eine Zeichenkette als Body und kennzeichnet sie als Formulardaten, das Format, das ein Browser für ein einfaches HTML-Formular verwendet:

bash
curl -d "name=Ada&city=Paris" https://api.example.com/signup

Unser Server erhielt POST, Content-Type: application/x-www-form-urlencoded und name=Ada&city=Paris. Mehrere -d-Optionen werden mit & verbunden, -d "a=1" -d "b=2" kam also als a=1&b=2 an.

-d sendet Text so, wie Sie ihn tippen; ein Wert mit Leerzeichen, & oder = zerfällt daher in falsche Felder. --data-urlencode kodiert den Wert für Sie:

bash
curl --data-urlencode "q=red shoes & bags" https://api.example.com/search

Der Server erhielt q=red+shoes+%26+bags, ein einziges Feld mit erhaltenem Kaufmanns-Und. Will ein Endpoint die Felder stattdessen in der Adresse, ergänzen Sie -G: Aus -G -d "q=shoes" -d "page=2" wurde GET /search?q=shoes&page=2 ohne Body.

Wie senden Sie JSON per POST mit curl?

Nutzen Sie --json ab curl 7.82.0, oder setzen Sie den Header in älteren Versionen selbst. -d allein sagt nie „das ist JSON“:

bash
# Falsch für die meisten JSON-APIs: JSON-Body, aber als Formular gekennzeichnet
curl -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

# Funktioniert mit jeder curl-Version
curl -H "Content-Type: application/json" -d '{"sku":"A-100","qty":2}' https://api.example.com/orders

# Ab curl 7.82.0
curl --json '{"sku":"A-100","qty":2}' https://api.example.com/orders

Auf unserem Testrechner kam der erste Befehl als application/x-www-form-urlencoded an, und unser reiner JSON-Test-Endpoint lehnte ihn mit 415 ab. Der zweite kam als application/json mit Accept: */* an, der dritte zusätzlich mit Accept: application/json, und der Endpoint antwortete mit 201 Created.

--json steht für --data-binary plus diese beiden Header, und ein Header, den Sie mit -H setzen, ersetzt den, den curl ergänzen würde. Prüfen Sie Ihre Version mit curl --version: Ubuntu 22.04 etwa liefert curl 7.81.0 aus, eine Version vor --json. Skripte für ältere Server sollten deshalb bei der -H-Form bleiben.

Wie senden Sie JSON aus einer Datei?

Übergeben Sie die Datei mit @: --json @order.json in neuen Versionen, --data-binary @order.json mit einem Content-Type-Header in alten. Verzichten Sie auf -d @order.json, wenn die Bytes exakt bleiben müssen:

bash
curl --json @order.json https://api.example.com/orders
curl -H "Content-Type: application/json" --data-binary @order.json https://api.example.com/orders

Mit einer vierzeiligen order.json lieferte -d @order.json 29 Bytes in einer Zeile, weil curl bei so gelesenen Dateien Wagenrückläufe und Zeilenumbrüche entfernt. --data-binary und --json lieferten alle 33 Bytes. Einem JSON-Parser ist das egal, einer signierten Anfrage oder einer CSV-Datei nicht.

Eine Datei beendet auch die meisten Probleme mit Anführungszeichen, weil die Shell das JSON nie anfasst. @- liest den Body aus der Standardeingabe, sodass ein Skript ihn erzeugen kann: python make_order.py | curl --json @- https://api.example.com/orders.

Wie ergänzen Sie Header in einer curl-POST-Anfrage?

Geben Sie jedem Header ein eigenes -H "Name: value"; wiederholen Sie die Option so oft wie nötig:

bash
curl --json @order.json \
  -H "Idempotency-Key: 7f3c9a10" \
  -H "X-Request-Source: nightly-sync" \
  https://api.example.com/orders

Ein Header, den Sie setzen, ersetzt curls eigenen Header gleichen Namens; so ändern Sie Accept oder User-Agent. Ein leerer Wert entfernt ihn: Mit -H "Content-Type:" erhielt unser Server gar keinen Content-Type.

-H-Header werden nach einer Weiterleitung erneut gesendet. curl hält Authorization und Cookie zurück, wenn die Weiterleitung zu einem anderen Host führt, ein Schlüssel in einem Header wie X-API-Key reist aber mit. Seien Sie also vorsichtig, wenn Sie -L ergänzen.

Wie laden Sie eine Datei mit curl -F hoch?

Nutzen Sie -F mit @ vor dem Dateinamen. curl sendet dann multipart/form-data, das Format eines HTML-Formulars mit Dateifeld:

bash
curl -F "title=Q3 report" -F "file=@report.pdf" https://api.example.com/uploads

Jedes -F wird zu einem benannten Teil. Wir haben eine Textdatei hochgeladen, report.txt, und unser Server sah einen Textteil title und einen Dateiteil file mit filename="report.txt" und Content-Type: text/plain, den curl aus der Dateiendung erraten hatte. Setzen Sie den Typ, wenn die Vermutung falsch ist: -F "file=@scan.bin;type=application/pdf".

< statt @ setzt den Inhalt einer Datei in ein normales Textfeld, etwa -F "notes=<notes.txt". -F und -d lassen sich nicht kombinieren: Unser curl brach mit You can only select one HTTP request method! ab, bevor es irgendetwas sendete. Der Feldname muss der Dokumentation der API entsprechen.

Wie authentifizieren Sie eine POST-Anfrage mit curl?

Senden Sie, was die API verlangt: -u user:pass für Basic-Authentifizierung oder einen Authorization-Header für ein Token. Mit -u user:pass erhielt unser Server Authorization: Basic dXNlcjpwYXNz, nur die Base64-Form von user:pass; verwenden Sie das also ausschließlich über HTTPS.

Ein Bearer-Token lesen Sie am besten aus einer Umgebungsvariable, damit es nicht in Ihrem Shell-Verlauf landet:

bash
export API_TOKEN="ihr-token"
curl --json @order.json -H "Authorization: Bearer $API_TOKEN" https://api.example.com/orders

--oauth2-bearer "$API_TOKEN" erzeugt denselben Header. Manche APIs wollen den Schlüssel in einem eigenen Header, etwa X-API-Key.

Wann brauchen Sie -X POST?

Mit einer Body-Option fast nie. Mit -v gab unser curl bei -X POST -d "x=1" den Hinweis Note: Unnecessary use of -X or --request, POST is already inferred. aus; laut Manpage ändert -X nur das Wort in der Anfragezeile. Nützlich ist es für andere Methoden mit Body: curl -X PUT --json '{"qty":3}' ... kam als PUT mit dem JSON an.

Schädlich wird -X zusammen mit -L (Weiterleitungen folgen). Wir haben an eine Adresse gesendet, die mit 302 Found antwortete:

  • Mit -L -d "x=1" folgte curl mit einem GET ohne Body, wie es die Manpage für 301, 302 und 303 beschreibt.
  • Mit -L -X POST -d "x=1" war die nächste Anfrage ein POST mit leerem Body: Die Methode war erzwungen, die Daten nicht.
  • Mit -L --post302 -d "x=1" war die nächste Anfrage ein POST mit dem ursprünglichen Body.

Wenn ein POST eine Weiterleitung überstehen muss, nutzen Sie also --post301, --post302 oder --post303, oder senden Sie direkt an die endgültige Adresse.

Wie sehen Sie Status und Header der Antwort?

Ergänzen Sie -i für Statuszeile und Antwort-Header, -v für Anfrage und Antwort oder -w nur für ausgewählte Werte:

bash
curl -i --json @order.json https://api.example.com/orders
curl -s -o /dev/null -w "%{http_code}\n" --json @order.json https://api.example.com/orders

Der erste Befehl gab vor dem JSON HTTP/1.1 201 Created aus. Der zweite gab nur 201 aus: -s blendet die Fortschrittsanzeige aus, -o /dev/null verwirft den Body (-o NUL unter Windows). "%{http_code} %{content_type} %{time_total}s\n" lieferte uns 201 application/json 0.001347s.

Ergänzen Sie in Skripten --fail-with-body: curl beendet sich bei Status 400 oder höher mit einem Fehler, gibt die Meldung des Servers aber trotzdem aus. Für eine Anfrage, die sich seltsam verhält, nutzen Sie -v; die Zeilen, die mit > beginnen, sind genau das, was curl gesendet hat.

Wie schreiben Sie curl-POST-Befehle unter Windows?

Windows 10 und 11 bringen echtes curl als curl.exe mit, doch in Windows PowerShell 5.1 ist das Wort curl ein Alias für das Cmdlet Invoke-WebRequest. Auf unserem Rechner scheiterte curl -d "x=1" ... in PowerShell 5.1 mit A positional parameter cannot be found that accepts argument 'x=1'. Tippen Sie curl.exe, wie es auch curls Seite zum Windows-Build empfiehlt.

Das größere Problem sind die Anführungszeichen. JSON in einfachen Anführungszeichen, die Form aus jedem Linux-Beispiel, verhält sich in jeder Shell anders:

ShellForm, die funktionierteWas die naive Form sendete
cmd.exe-d "{\"sku\":\"A-100\"}"'{sku:A-100}'
PowerShell 5.1--json '{\"sku\":\"A-100\"}'{sku:A-100}
PowerShell 7.3+--json '{"sku":"A-100"}'Hier nicht getestet
Jede Shell--json "@order.json"Die Datei, unverändert

In cmd sind einfache Anführungszeichen keine Begrenzer, sie wurden also Teil des Bodys, und die inneren doppelten Anführungszeichen verschwanden. In PowerShell 5.1 kam '{"sku":"A-100","qty":2}' bei unserem Server als {sku:A-100,qty:2} an, und der JSON-Endpoint antwortete mit 400. Jedes innere Anführungszeichen als \" zu maskieren, löste beide Fälle.

Microsofts Referenz about_Parsing erklärt den Grund: PowerShell 7.3 hat geändert, wie Argumente mit eingebetteten Anführungszeichen an Programme wie curl.exe übergeben werden, eine inkompatible Änderung gegenüber 5.1. PowerShell 7 war auf unserem Testrechner nicht installiert; diese Zeile folgt daher der Dokumentation. Setzen Sie in PowerShell alles, was mit @ beginnt, in Anführungszeichen, etwa "@order.json"; schreiben Sie in einer .cmd-Batchdatei %%{http_code} für -w. Die sicherste Gewohnheit unter Windows ist die Datei: Dann bleibt der Shell nichts mehr, was sie kaputt machen könnte.

Wie senden Sie eine curl-POST-Anfrage über einen Proxy?

Ergänzen Sie -x mit der Proxy-Adresse; die Body-Optionen bleiben gleich:

bash
curl -x http://user:pass@pr.proxynet.io:8000 \
  --json @order.json https://api.example.com/orders

Bei einem HTTPS-Ziel bittet curl den Proxy zuerst um einen CONNECT-Tunnel und sendet den POST dann innerhalb der verschlüsselten Verbindung; der Proxy sieht also den Hostnamen, nicht aber Ihr JSON. SOCKS5, Umgebungsvariablen und .curlrc behandelt cURL mit Proxy verwenden.

Ein Proxy hilft, wenn die Anfrage von einer bestimmten Adresse oder aus einem bestimmten Land kommen muss, zum Beispiel um zu sehen, wie Ihr eigener Checkout einem Käufer in einer anderen Region antwortet. Ein HTTPS-Proxy nimmt genau diese Optionen, mit Benutzername und Passwort oder mit der IP Ihres Servers auf der IP-Whitelist.

Braucht der Test Privatanschlüsse in einem gewählten Land oder einer Stadt, nutzt ein Residential-Proxy dieselbe -x-Zeile, mit Land und Sitzung im Benutzernamen.

Wo werden curl-POST-Anfragen eingesetzt?

Entwickler probieren eine API mit einem curl-POST aus, bevor sie Code schreiben, weil der Befehl nichts verbirgt. Supportteams fragen nach dem fehlschlagenden curl-Befehl, da er das Problem auf jedem Rechner reproduziert. Webhook-Empfänger testet man, indem man ein Beispielereignis an den eigenen Endpoint sendet. Deploy-Skripte rufen interne APIs auf, um Jobs zu starten oder Releases zu veröffentlichen, und Monitoring-Jobs senden eine Testbestellung an ein Staging-System und schlagen Alarm, wenn die Antwort nicht mehr 201 lautet.

Häufige Fehler bei curl-POST-Anfragen und ihre Lösungen

  • 415 Unsupported Media Type. JSON mit -d und Formular-Kennzeichnung gesendet. Nutzen Sie --json oder -H "Content-Type: application/json".
  • 400 Bad Request mit JSON-Parse-Fehler. Von der Shell entfernte Anführungszeichen oder ein Tippfehler im JSON. Prüfen Sie mit -v oder verschieben Sie das JSON in eine Datei.
  • Der POST kommt als GET an. Eine Weiterleitung mit 301, 302 oder 303 zusammen mit -L. Senden Sie an die endgültige URL oder nutzen Sie die Optionen --post30x.
  • Leerer Body nach einer Weiterleitung. -X POST mit -L; lassen Sie -X weg.
  • 401 oder 403. Fehlendes oder falsches Token, oder $API_TOKEN ist in dieser Shell leer. Geben Sie die Variable zuerst aus.
  • A positional parameter cannot be found. curl in PowerShell 5.1 hat Invoke-WebRequest erreicht; tippen Sie curl.exe.
  • Ein Teil eines Headers wird als zweite Adresse behandelt. -H Content-Type: application/json ohne Anführungszeichen wird am Leerzeichen getrennt. Setzen Sie jeden -H-Wert in Anführungszeichen.
  • --json wird als unbekannt abgelehnt. curl älter als 7.82.0; nutzen Sie -H plus --data-binary.

Entscheidungshilfe

BedarfEmpfehlung
Formularfelder senden-d "a=1" -d "b=2"
Formularwert mit Leerzeichen oder &--data-urlencode
JSON senden, curl ab 7.82.0--json @file.json
JSON senden, älteres curl-H "Content-Type: application/json" --data-binary @file.json
Datei hochladen-F "file=@name.ext"
Authentifizierung per Token-H "Authorization: Bearer $API_TOKEN"
PUT oder PATCH mit Body-X PUT --json ...
POST, der eine Weiterleitung übersteht-L --post302 (oder 301/303)
Nur der Statuscode-s -o /dev/null -w "%{http_code}\n"
JSON unter Windowscurl.exe mit Datei und @

Häufige Fragen

Wie sende ich eine POST-Anfrage mit curl?

Geben Sie curl einen Body, dann sendet es einen POST: curl -d "name=Ada" https://api.example.com/form für Formulardaten oder curl --json '{"name":"Ada"}' https://api.example.com/users für JSON. -X POST ist nicht nötig.

Was ist der Unterschied zwischen -d und --json in curl?

Die Kennzeichnung unterscheidet sich. -d sendet Content-Type: application/x-www-form-urlencoded und entfernt Zeilenumbrüche aus Dateien; --json sendet Content-Type: application/json plus Accept: application/json und lässt Dateien unverändert. --json braucht curl 7.82.0 oder neuer.

Wie sende ich eine JSON-Datei per POST mit curl?

Nutzen Sie curl --json @data.json https://api.example.com/items. Bei curl älter als 7.82.0 nehmen Sie -H "Content-Type: application/json" --data-binary @data.json. Verzichten Sie auf -d @data.json, wenn es auf die exakten Bytes ankommt.

Wie sehe ich die Antwort-Header einer curl-POST-Anfrage?

Ergänzen Sie -i, um Statuszeile und Header vor dem Body auszugeben, oder -v, um Anfrage- und Antwort-Header zusammen zu sehen. Nur für den Statuscode nutzen Sie -s -o /dev/null -w "%{http_code}".

Warum funktioniert mein curl-POST unter Linux, aber nicht in PowerShell?

In Windows PowerShell 5.1 bedeutet curl Invoke-WebRequest, und 5.1 entfernt die doppelten Anführungszeichen innerhalb von JSON in einfachen Anführungszeichen, bevor curl.exe es erhält. Tippen Sie curl.exe, maskieren Sie innere Anführungszeichen als \" oder übergeben Sie das JSON aus einer Datei.

Wie übertrage ich einen curl-POST-Befehl nach Python?

Ordnen Sie jeden Teil zu: Aus --json wird json=, aus -d wird data=, aus -H wird headers= und aus -F wird files=. Eine vollständige Zuordnung mit getesteten Beispielen finden Sie in JSON mit Python Requests per POST senden.

Fazit

curl sendet einen POST, sobald es einen Body hat: -d für Formulardaten, --json für JSON ab 7.82.0, -H "Content-Type: application/json" mit --data-binary in älteren Versionen, -F für Uploads. Die meisten Fehler liegen an der Kennzeichnung, nicht an den Daten: Als Formular gesendetes JSON ergibt 415, -d @ verliert Zeilenumbrüche, und -X POST mit -L sendet nach einer Weiterleitung einen leeren POST. Was hinausging, prüfen Sie mit -v. Unter Windows tippen Sie curl.exe und legen JSON in eine Datei; muss die Anfrage von einer bestimmten Adresse oder aus einem bestimmten Land kommen, ergänzen Sie -x und lassen den Rest unverändert.

ChatGPT fragenClaude fragen