Bir API'nin belgelerinde sipariş oluşturmak için tek satırlık bir curl komutu var. Komutu yapıştırıyor, anahtarınızı ekliyor, Enter'a basıyorsunuz; sunucu 415 Unsupported Media Type döndürüyor ya da JSON gözünüze düzgün göründüğü hâlde invalid JSON diyerek 400 veriyor. Aynı satır bir iş arkadaşınızın Linux bilgisayarında çalışıyor. API'de bir sorun yok: komut, sandığınızdan farklı bir gövde ya da farklı bir Content-Type gönderdi; Windows'ta ise kabuk, JSON'daki tırnakları curl'e ulaşmadan sildi.
Bu yazıda -d ile form verisi göndermeyi, JSON'u --json ile ya da -H ve -d'yi birlikte kullanarak göndermeyi, gövdeyi dosyadan okumayı, -F ile dosya yüklemeyi, başlıkları (header) ve kimlik doğrulamayı, -X POST'un ne zaman gerektiğini, yanıtı okumayı ve cmd ile PowerShell'de tırnak kullanımını ele alıyoruz. Her komutu Windows 11'de, curl 8.22.0 ile, cmd ve Windows PowerShell 5.1 içinden çalıştırdık. Karşı tarafta kendi makinemizde çalışan küçük bir yankı (echo) sunucusu vardı; gelen isteğin yöntemini, Content-Type başlığını ve gövdesini olduğu gibi yazdırdı.
POST isteği nedir?
POST isteği, gövdesinde veri taşıyan ve sunucudan bu veriyle bir iş yapmasını isteyen HTTP isteğidir: sipariş oluşturmak, form kaydetmek, bir işi başlatmak gibi. HTTP standardı RFC 9110, POST'u hedef kaynağın istekle gelen içeriği kendi kurallarına göre işlemesi isteği olarak tanımlar.
GET yalnızca bir şeyi ister ve gövde taşımaz. POST ayrıca idempotent değildir, yani aynı POST'u iki kez göndermek iki sipariş oluşturabilir. İstek, endpoint ve durum kodu kavramları size yeniyse önce API Nedir ve Nasıl Çalışır? yazısına bakabilirsiniz.
Bir POST'ta iki parça en çok önemlidir. Gövde verinin kendisidir. Content-Type başlığı ise sunucuya bu gövdeyi nasıl okuyacağını söyler: form alanları, JSON ya da çok parçalı (multipart) bir yükleme olarak. curl ile yaşanan POST sorunlarının çoğu bu ikisinin uyuşmamasından çıkar.
curl POST isteğini nasıl gönderir?
curl, bir gövde seçeneği verdiğiniz anda kendiliğinden POST'a geçer; siz veriyi tarif edersiniz, yöntemi curl belirler:
- Bir gövde seçeneği eklersiniz.
-d,--data-binary,--data-urlencode,--jsonya da-Fisteği POST yapar. - curl bir
Content-Typeseçer.-dailesiapplication/x-www-form-urlencoded,--jsonapplication/json,-Fise sınır dizgisiyle (boundary) birliktemultipart/form-datagönderir. - curl gövdeyi hazırlar. Birden fazla
-dparçasını&ile birleştirir,-d @ile okunan dosyalardan satır sonlarını siler,--data-binaryve--jsonile dosyaları olduğu gibi bırakır. - İsteği gönderir. Önce
POST /orders HTTP/1.1satırı, ardındanContent-Length,Content-Typeve sizin-Hdeğerleriniz dahil başlıklar, en sonda gövde gider. - Sunucu önce
Content-Type'a bakar. Form türünde veri alan bir JSON API'si isteği 415 ile reddeder ya da ayrıştıramayıp 400 döndürür. - curl yanıtın gövdesini yazdırır. Durum kodu ve başlıklar,
-i,-vya da-wile istemediğiniz sürece görünmez.
İstek gövdesi için hangi curl seçeneği kullanılmalı?
Sunucunun beklediği biçime uyan seçeneği seçin. Aşağıdaki tablo, her seçenekle yankı sunucumuza ne ulaştığını gösteriyor:
| Seçenek | Gönderilen Content-Type | Gövdeye ne olur | Ne için |
|---|---|---|---|
-d / --data | application/x-www-form-urlencoded | Yazıldığı gibi; @dosya satır sonlarını kaybeder | HTML tarzı formlar |
--data-urlencode | application/x-www-form-urlencoded | Değer yüzde kodlanır | Boşluk ya da & içeren değerler |
--data-binary | application/x-www-form-urlencoded | Bayt bayt aynı | Birebir kalması gereken dosyalar |
--json | application/json | Bayt bayt aynı, Accept eklenir | JSON API'leri (7.82.0+) |
-F / --form | multipart/form-data | Adlandırılmış parçalara bölünür | Dosya yükleme |
Bu seçeneklerin hepsi, yazıdaki her seçeneğin başvuru kaynağı olan curl kılavuzunda anlatılır.
-d ile form verisi nasıl gönderilir?
-d, bir metni gövde olarak gönderir ve onu form verisi diye etiketler; tarayıcının basit bir HTML formunu gönderirken kullandığı biçim budur:
curl -d "name=Ada&city=Paris" https://api.example.com/signupSunucumuz POST, Content-Type: application/x-www-form-urlencoded ve name=Ada&city=Paris gövdesini aldı. Birden fazla -d seçeneği & ile birleştirilir; -d "a=1" -d "b=2" sunucuya a=1&b=2 olarak ulaştı.
-d metni yazdığınız gibi gönderir; bu yüzden içinde boşluk, & ya da = bulunan bir değer yanlış alanlara bölünür. --data-urlencode değeri sizin yerinize kodlar:
curl --data-urlencode "q=red shoes & bags" https://api.example.com/searchSunucu q=red+shoes+%26+bags aldı: & işareti bozulmadan tek bir alan. Endpoint alanları gövdede değil adreste bekliyorsa -G ekleyin: -G -d "q=shoes" -d "page=2" gövdesiz bir GET /search?q=shoes&page=2 isteğine dönüştü.
curl ile JSON nasıl POST edilir?
curl 7.82.0 ve sonrasında --json kullanın; daha eski sürümlerde başlığı kendiniz ekleyin. -d tek başına hiçbir zaman "bu bir JSON" demez:
# Çoğu JSON API'si için yanlış: gövde JSON, etiket form verisi
curl -d '{"sku":"A-100","qty":2}' https://api.example.com/orders
# Her curl sürümünde çalışır
curl -H "Content-Type: application/json" -d '{"sku":"A-100","qty":2}' https://api.example.com/orders
# curl 7.82.0 ve sonrası
curl --json '{"sku":"A-100","qty":2}' https://api.example.com/ordersTest makinemizde ilk komut application/x-www-form-urlencoded olarak ulaştı ve yalnız JSON kabul eden test endpoint'imiz onu 415 ile reddetti. İkincisi application/json ve Accept: */* ile, üçüncüsü buna ek olarak Accept: application/json ile geldi ve endpoint 201 Created döndürdü.
--json, --data-binary ile bu iki başlığın kısaltmasıdır; -H ile verdiğiniz başlık onun ekleyeceği başlığın yerine geçer. Sürümünüzü curl --version ile kontrol edin. Örneğin Ubuntu 22.04, --json'dan bir önceki sürüm olan curl 7.81.0 ile gelir; eski sunucularda da çalışması gereken betiklerde -H'li biçimi koruyun.
JSON dosyadan nasıl gönderilir?
Dosyayı @ ile verin: yeni sürümlerde --json @order.json, eski sürümlerde bir Content-Type başlığıyla birlikte --data-binary @order.json. Baytların aynen kalması gerekiyorsa -d @order.json kullanmayın:
curl --json @order.json https://api.example.com/orders
curl -H "Content-Type: application/json" --data-binary @order.json https://api.example.com/ordersDört satırlık bir order.json ile -d @order.json tek satırlık 29 bayt ulaştırdı; curl bu yolla okunan dosyalardan satır başı ve satır sonu karakterlerini siler. --data-binary ve --json 33 baytın tamamını ulaştırdı. JSON ayrıştırıcısı bunu umursamaz, ama imzalı bir istek ya da bir CSV dosyası umursar.
Dosya, tırnak sorunlarının da çoğunu bitirir, çünkü kabuk JSON'a hiç dokunmaz. @- gövdeyi standart girdiden okur; böylece gövdeyi bir betik üretip curl'e aktarabilir: python make_order.py | curl --json @- https://api.example.com/orders.
curl POST isteğine header nasıl eklenir?
Her başlığı ayrı bir -H "Ad: değer" ile verin; gerektiği kadar tekrarlayabilirsiniz:
curl --json @order.json \
-H "Idempotency-Key: 7f3c9a10" \
-H "X-Request-Source: nightly-sync" \
https://api.example.com/ordersSizin verdiğiniz başlık, curl'ün aynı adlı kendi başlığının yerine geçer; Accept ya da User-Agent bu yolla değiştirilir. Boş değer başlığı tamamen kaldırır: -H "Content-Type:" ile sunucumuza hiç Content-Type ulaşmadı.
-H ile verilen başlıklar yönlendirmeden sonra da gönderilir. Yönlendirme başka bir host'a gidiyorsa curl Authorization ve Cookie başlıklarını göndermez; ama X-API-Key gibi bir başlıktaki anahtar gider. -L eklerken bunu hesaba katın.
curl -F ile dosya nasıl yüklenir?
-F kullanın ve dosya adının önüne @ koyun. curl bu durumda multipart/form-data gönderir; dosya alanı olan bir HTML formunun biçimi budur:
curl -F "title=Q3 report" -F "file=@rapor.pdf" https://api.example.com/uploadsHer -F adlandırılmış bir parçaya dönüşür. Testte bir metin dosyası (report.txt) yükledik. Sunucumuz title adlı bir metin parçası ve filename="report.txt" ile Content-Type: text/plain taşıyan file adlı bir dosya parçası gördü; türü curl dosya uzantısından tahmin etti. Tahmin yanlışsa türü siz verin: -F "file=@tarama.bin;type=application/pdf".
@ yerine < yazarsanız dosyanın içeriği dosya adı olmadan sıradan bir metin alanına konur: -F "notes=<notlar.txt". -F ile -d birlikte kullanılamaz; curl'ümüz hiçbir şey göndermeden You can only select one HTTP request method! uyarısıyla durdu. Alan adı, API belgelerinde yazanla aynı olmalıdır.
POST isteğinde kimlik doğrulama nasıl yapılır?
API'nin istediğini gönderin: Basic kimlik doğrulama için -u user:pass, token için bir Authorization başlığı. -u user:pass ile sunucumuza Authorization: Basic dXNlcjpwYXNz ulaştı; bu, user:pass ifadesinin yalnızca Base64 biçimidir, bu yüzden yalnız HTTPS üzerinden kullanın.
Bearer token'ı bir ortam değişkeninden okuyun ki kabuk geçmişinizde kalmasın:
export API_TOKEN="token-degeriniz"
curl --json @order.json -H "Authorization: Bearer $API_TOKEN" https://api.example.com/orders--oauth2-bearer "$API_TOKEN" aynı başlığı sizin yerinize oluşturur. Bazı API'ler anahtarı X-API-Key gibi kendine ait bir başlıkta bekler.
-X POST ne zaman gerekir?
Bir gövde seçeneği varken neredeyse hiçbir zaman. -v ile çalıştırdığımızda curl, -X POST -d "x=1" için Note: Unnecessary use of -X or --request, POST is already inferred. notunu yazdı; kılavuz da -X'in yalnızca istek satırındaki kelimeyi değiştirdiğini söyler. Gövde taşıyan başka yöntemler için işe yarar: curl -X PUT --json '{"qty":3}' ... sunucuya JSON gövdeli bir PUT olarak ulaştı.
-X, -L (yönlendirmeleri izle) ile birlikte zarar verir. 302 Found döndüren bir adrese POST gönderdik:
-L -d "x=1"ile curl yönlendirmeyi gövdesiz bir GET ile izledi; kılavuz 301, 302 ve 303 için bu davranışı anlatır.-L -X POST -d "x=1"ile sonraki istek boş gövdeli bir POST oldu: yöntem zorlandı, veri değil.-L --post302 -d "x=1"ile sonraki istek özgün gövdeyi taşıyan bir POST oldu.
Yani bir POST'un yönlendirmeden sağ çıkması gerekiyorsa -X POST yerine --post301, --post302 ya da --post303 kullanın veya doğrudan son adrese gönderin.
Yanıtın durum kodu ve başlıkları nasıl görülür?
Durum satırı ve yanıt başlıkları için -i, istek ile yanıtı birlikte görmek için -v, yalnız seçtiğiniz değerler için -w ekleyin:
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İlki JSON'dan önce HTTP/1.1 201 Created yazdı. İkincisi yalnızca 201 yazdı: -s ilerleme göstergesini gizler, -o /dev/null gövdeyi atar (Windows'ta -o NUL). "%{http_code} %{content_type} %{time_total}s\n" bize 201 application/json 0.001347s verdi.
Betiklerde --fail-with-body ekleyin: curl 400 ve üzeri durum kodlarında hata koduyla çıkar ama sunucunun mesajını yine yazdırır. Tuhaf davranan bir istekte -v kullanın; > ile başlayan satırlar curl'ün tam olarak ne gönderdiğini gösterir.
Windows'ta curl POST komutları nasıl yazılır?
Windows 10 ve 11 gerçek curl'ü curl.exe olarak getirir, ama Windows PowerShell 5.1'de curl kelimesi Invoke-WebRequest komutunun takma adıdır. Makinemizde PowerShell 5.1'e yazılan curl -d "x=1" ... komutu A positional parameter cannot be found that accepts argument 'x=1'. hatasıyla durdu. curl.exe yazın; curl'ün Windows sürümü sayfası da aynısını önerir.
Asıl sorun tırnaklardır. Linux örneklerinin hepsinde görülen tek tırnaklı JSON, her kabukta farklı davranır:
| Kabuk | Çalışan biçim | Düz biçimin gönderdiği |
|---|---|---|
| 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"}' | Burada test edilmedi |
| Her kabuk | --json "@order.json" | Dosya, değişmeden |
cmd'de tek tırnak bir tırnak karakteri sayılmaz; bu yüzden gövdenin parçası oldu, içteki çift tırnaklar ise kayboldu. PowerShell 5.1'de '{"sku":"A-100","qty":2}' sunucumuza {sku:A-100,qty:2} olarak ulaştı ve JSON endpoint'i 400 döndürdü. İçteki her tırnağı \" diye kaçırmak iki kabukta da sorunu çözdü.
Microsoft'un about_Parsing başvurusu nedenini açıklar: PowerShell 7.3, içinde tırnak bulunan argümanların curl.exe gibi programlara aktarılma biçimini değiştirdi ve bunu 5.1'e göre geriye dönük uyumsuz bir değişiklik olarak tanımlar. Test makinemizde PowerShell 7 kurulu değildi; o satır belgelere dayanır. PowerShell'de @ ile başlayan her şeyi tırnağa alın ("@order.json"); bir .cmd toplu iş dosyasında ise -w için %%{http_code} yazın. Windows'ta en güvenli alışkanlık dosyadır: kabuğun bozabileceği bir şey kalmaz.
curl POST isteği proxy üzerinden nasıl gönderilir?
Proxy adresini -x ile ekleyin; gövde seçenekleri aynen kalır:
curl -x http://user:pass@pr.proxynet.io:8000 \
--json @order.json https://api.example.com/ordersHTTPS bir hedefte curl önce proxy'den bir CONNECT tüneli ister, sonra POST'u şifreli bağlantının içinden gönderir; proxy host adını görür ama JSON'unuzu görmez. SOCKS5, ortam değişkenleri ve .curlrc ayarları cURL ile Proxy Nasıl Kullanılır? yazısında anlatılıyor.
Proxy, isteğin belirli bir adresten ya da ülkeden çıkması gerektiğinde işe yarar; örneğin kendi ödeme sayfanızın başka bir bölgede alışveriş yapan birine nasıl yanıt verdiğini görmek için. Bir HTTPS Proxy tam olarak bu seçeneklerle, kullanıcı adı ve şifreyle ya da sunucunuzun IP'sini IP whitelist'e ekleyerek çalışır.
Test, seçtiğiniz ülke ya da şehirde ev bağlantıları gerektiriyorsa bir Residential Proxy aynı -x satırını kullanır; ülke ve oturum kullanıcı adının içinde yer alır.
curl POST istekleri nerelerde kullanılır?
Geliştiriciler bir API'yi kod yazmadan önce curl POST ile dener, çünkü komut hiçbir şeyi gizlemez. Destek ekipleri hata veren curl komutunu ister, çünkü sorun bu komutla her makinede yeniden üretilebilir. Webhook alan sistemler, kendi endpoint'inize örnek bir olay gönderilerek test edilir. Dağıtım betikleri iş başlatmak ya da sürüm yayımlamak için iç API'leri çağırır; izleme işleri bir test ortamına deneme siparişi gönderir ve yanıt 201 olmaktan çıktığında uyarı verir.
Sık görülen curl POST hataları ve çözümleri
- 415 Unsupported Media Type. JSON,
-dile ve form etiketiyle gitti.--jsonya da-H "Content-Type: application/json"kullanın. - JSON ayrıştırma hatasıyla 400 Bad Request. Tırnakları kabuk sildi ya da JSON'da yazım hatası var.
-vile bakın ya da JSON'u bir dosyaya taşıyın. - POST, GET olarak ulaşıyor.
-Lile 301, 302 ya da 303 yönlendirmesi. Son adrese gönderin ya da--post30xseçeneklerini kullanın. - Yönlendirmeden sonra gövde boş.
-Lile birlikte-X POST;-X'i kaldırın. - 401 ya da 403. Token eksik ya da yanlış, veya
$API_TOKENbu kabukta boş. Önce değişkeni yazdırın. A positional parameter cannot be found. PowerShell 5.1'decurlyazdınız veInvoke-WebRequestçalıştı;curl.exeyazın.- Başlığın bir kısmı ikinci bir adres sanılıyor. Tırnaksız
-H Content-Type: application/jsonboşlukta bölünür. Her-Hdeğerini tırnağa alın. --jsonbilinmeyen seçenek diye reddediliyor. curl 7.82.0'dan eski;-Hile--data-binarykullanın.
Karar rehberi
| İhtiyaç | Öneri |
|---|---|
| Form alanları göndermek | -d "a=1" -d "b=2" |
Boşluk ya da & içeren form değeri | --data-urlencode |
| JSON göndermek, curl 7.82.0+ | --json @dosya.json |
| JSON göndermek, eski curl | -H "Content-Type: application/json" --data-binary @dosya.json |
| Dosya yüklemek | -F "file=@ad.uzanti" |
| Token ile kimlik doğrulama | -H "Authorization: Bearer $API_TOKEN" |
| Gövdeli PUT ya da PATCH | -X PUT --json ... |
| Yönlendirmeden sağ çıkması gereken POST | -L --post302 (ya da 301/303) |
| Yalnız durum kodu | -s -o /dev/null -w "%{http_code}\n" |
| Windows'ta JSON | Dosya ve @ ile curl.exe |
Sıkça sorulan sorular
curl ile POST isteği nasıl gönderilir?
curl'e bir gövde verin, POST gönderir: form verisi için curl -d "name=Ada" https://api.example.com/form, JSON için curl --json '{"name":"Ada"}' https://api.example.com/users. -X POST gerekmez.
curl'de -d ile --json arasındaki fark nedir?
Fark etikettedir. -d, Content-Type: application/x-www-form-urlencoded gönderir ve dosyalardan satır sonlarını siler; --json ise Content-Type: application/json ile Accept: application/json gönderir ve dosyaları olduğu gibi bırakır. --json için curl 7.82.0 ya da sonrası gerekir.
curl ile JSON dosyası nasıl POST edilir?
curl --json @veri.json https://api.example.com/items kullanın. 7.82.0'dan eski curl'de -H "Content-Type: application/json" --data-binary @veri.json yazın. Baytların aynen kalması gerekiyorsa -d @veri.json kullanmayın.
curl POST isteğinin yanıt başlıkları nasıl görülür?
Durum satırını ve başlıkları gövdeden önce yazdırmak için -i, istek ve yanıt başlıklarını birlikte görmek için -v ekleyin. Yalnız durum kodu için -s -o /dev/null -w "%{http_code}" kullanın.
curl POST komutum Linux'ta çalışıyor, PowerShell'de neden çalışmıyor?
Windows PowerShell 5.1'de curl, Invoke-WebRequest anlamına gelir; ayrıca 5.1, tek tırnaklı JSON'un içindeki çift tırnakları curl.exe'ye ulaşmadan siler. curl.exe yazın, içteki tırnakları \" diye kaçırın ya da JSON'u dosyadan verin.
curl POST komutu Python'a nasıl çevrilir?
Her parçayı eşleyin: --json json=, -d data=, -H headers=, -F ise files= olur. Test edilmiş örneklerle tam eşleme Python Requests ile POST ve JSON yazısında.
Özet
curl, bir gövdesi olduğu anda POST gönderir: form verisi için -d, 7.82.0 ve sonrasında JSON için --json, eski sürümlerde --data-binary ile birlikte -H "Content-Type: application/json", dosya yüklemek için -F. Hataların çoğu veriden değil etiketten çıkar: form verisi olarak giden JSON 415 döndürür, -d @ satır sonlarını siler, -L ile birlikte -X POST yönlendirmeden sonra boş bir POST gönderir. Neyin gittiğini -v ile kontrol edin. Windows'ta curl.exe yazın ve JSON'u dosyada tutun; istek belirli bir adresten ya da ülkeden çıkmalıysa -x ekleyin, komutun geri kalanını değiştirmeyin.




