DEV Community

Cover image for Apidog'da Dosya Yükleme API'leri (multipart/form-data) Nasıl Test Edilir
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

Apidog'da Dosya Yükleme API'leri (multipart/form-data) Nasıl Test Edilir

Bir dosya alan uç noktanız hazır: kullanıcı profil resmini POST /avatars adresine, imzalı PDF'i ise POST /documents adresine gönderiyor. Şimdi bunu gerçek HTTP isteğiyle test etmeniz gerekir: yerel bir dosya seçin, form alanına ekleyin, isteği gönderin ve yanıtı doğrulayın.

Apidog'u bugün deneyin

Dosya yüklemeleri JSON gövdesiyle çalışmaz; multipart/form-data kullanır. Bu nedenle yalnızca JSON yapıştırıp isteği gönderemezsiniz. Dosya alanlarını destekleyen bir istek oluşturucuya ve testi daha sonra Runner veya CLI ile çalıştırdığınızda dosyayı bulabilen bir yürütme ortamına ihtiyacınız vardır. Apidog, hem manuel istek oluşturmayı hem de test otomasyonunu destekler. Çok parçalı istek yapısını daha ayrıntılı öğrenmek için API'lerde dosya yükleme rehberine, tarayıcı tarafı kullanım için ise MDN FormData referansına bakabilirsiniz.

multipart/form-data nedir ve yüklemelerde neden kullanılır?

Bir API istek gövdesi form-data, x-www-form-urlencoded, JSON, XML, raw veya binary olabilir. Çoğu API çağrısında JSON yeterlidir. Ancak dosya gönderirken multipart/form-data kullanmanız gerekir.

form-data, aşağıdaki başlığa karşılık gelir:

Content-Type: multipart/form-data
Enter fullscreen mode Exit fullscreen mode

Bu format, gövdeyi ayrı parçalara böler. Her parça kendi alan adına ve içeriğine sahiptir:

  • Bir parça title gibi düz metin olabilir.
  • Bir parça PNG, JPEG veya PDF dosyasının ham baytlarını içerebilir.
  • Tüm parçalar aynı HTTP isteğinde gönderilir.

x-www-form-urlencoded görünüşte benzer anahtar-değer alanları sunar, ancak dosya taşımak için uygun değildir. Yalnızca kısa, skaler değerler içeren formlarda kullanın. Uç noktanız bir dosya kabul ediyorsa form-data seçin.

Apidog'da her form-data parametresinin bir türü vardır: string, integer, file vb. Bir alanın türünü file yaptığınızda Apidog bu değeri metin olarak değil, yerel dosya olarak işler.

Tek dosya yüklemesi gönderin ve yanıtı doğrulayın

Örnek olarak POST /avatars uç noktasını test edelim. Bu uç nokta avatar adlı bir dosya alanı alıyor ve depolanan dosyanın URL'sini JSON olarak döndürüyor.

1. Gövde türünü form-data olarak ayarlayın

Yeni bir istek oluşturun veya mevcut uç noktanızı açın:

POST /avatars
Enter fullscreen mode Exit fullscreen mode

Ardından:

  1. Body / Gövde sekmesini açın.
  2. Gövde türü olarak form-data seçin.
  3. Apidog'un Content-Type: multipart/form-data başlığını oluşturmasına izin verin.

2. Dosya alanını ekleyin

Yeni bir parametre ekleyin:

Alan Değer
Key avatar
Type file

Alan türünü string yerine file olarak seçtiğinizde değer hücresi dosya seçiciye dönüşür.

3. Yerel dosyayı seçin

avatar satırındaki Yükle seçeneğine tıklayın ve örneğin şu dosyayı seçin:

jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Apidog dosyanın yerel yolunu kaydeder.

Apidog dosyanın baytlarını buluta yüklemez; yalnızca yerel dosya yolunu saklar. Bu ayrıntı, isteği başka bir bilgisayarda veya Runner/CLI ortamında çalıştırırken önemlidir.

4. İsteği gönderin

Gönder düğmesine tıklayın. Apidog:

  1. Dosyayı kayıtlı yerel yoldan okur.
  2. multipart/form-data gövdesini oluşturur.
  3. HTTP isteğini gönderir.

Başarılı bir yanıt şu yapıda olabilir:

{
  "id": "usr_8842",
  "avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
  "sizeBytes": 48210,
  "contentType": "image/png"
}
Enter fullscreen mode Exit fullscreen mode

5. Yanıt doğrulayıcılarını ekleyin

Yalnızca 200 yanıtı almak testin başarılı olduğu anlamına gelmez. Yanıt gövdesindeki kritik alanları da doğrulayın.

Örneğin:

durum kodu == 200
$.avatarUrl mevcut
$.contentType == "image/png"
Enter fullscreen mode Exit fullscreen mode

Apidog'da bunları istek sonrası doğrulayıcılar olarak ekleyebilirsiniz:

  • Durum kodu için 200 doğrulaması
  • $.avatarUrl için varlık doğrulaması
  • $.contentType için eşitlik doğrulaması

JSONPath ve doğrulayıcı seçenekleri hakkında daha fazla bilgi için API doğrulayıcıları rehberini inceleyin.

Aynı isteğin curl karşılığı şöyledir:

curl -X POST https://api.example.com/avatars \
  -F "avatar=@jane-profile.png"
Enter fullscreen mode Exit fullscreen mode

Buradaki -F, çok parçalı form alanı oluşturur. @ işareti ise curl'e dosya içeriğini yerel diskten okumasını söyler.

Aynı istekte dosya ve JSON gönderin

Gerçek dünyadaki uç noktalar çoğunlukla yalnızca dosya kabul etmez. Örneğin POST /documents, PDF ile birlikte başlık, kategori ve etiketler de isteyebilir.

Basit meta veriler: ayrı form alanları kullanın

Dosya alanınızın yanına düz alanlar ekleyin:

Key Type Örnek değer
file file q3-invoice.pdf
title string Q3 Faturası
category string faturalama

Bu alanların tamamı aynı multipart/form-data isteğiyle gönderilir.

Yapılandırılmış meta veriler: JSON'u string alanında gönderin

Meta veri dizi veya iç içe nesne içeriyorsa, metadata adında bir string alanı oluşturup JSON değerini doğrudan ekleyin:

{
  "title": "Q3 Faturası",
  "category": "faturalama",
  "tags": ["fatura", "2026", "ödendi"]
}
Enter fullscreen mode Exit fullscreen mode

İstek iki ana parçadan oluşur:

  • file: Türü file olan PDF dosyası
  • metadata: Türü string olan JSON metni

Sunucu dosyayı bir parçadan okur, JSON metnini diğer parçadan ayrıştırır. Bu yaklaşım yaygındır; Stripe dosya yükleme belgeleri dosya parçasını düz alanlarla birlikte kullanan gerçek bir örnek sunar. Postman'dan geçiş yapıyorsanız Postman'da dosya ve JSON verilerini yükleme rehberi de aynı modelin Apidog karşılığını gösterir.

Birden fazla dosya ekleyin

Birden fazla dosya için ek file türünde alanlar oluşturun. Örneğin:

Key Type
file file
thumbnail file

POST /documents uç noktanız ana belge ve küçük resim bekliyorsa, her alan için ayrı bir Yükle seçeneği kullanın. Özel bir “çoklu dosya modu” gerekmez; API'nin beklediği her dosya parçası için bir file alanı eklemeniz yeterlidir.

İsteği tekrarlanabilir test senaryosuna dönüştürün

Tek bir manuel istek, uç noktanın o an çalıştığını gösterir. Gerilemeleri yakalamak için yüklemeyi bir test senaryosuna ekleyin.

Örnek akış:

  1. POST /avatars ile resmi yükleyin.
  2. Yanıttaki id değerini kaydedin.
  3. GET /users/{id} isteğini gönderin.
  4. Avatar URL'sinin kalıcı olduğunu doğrulayın.

Yükleme isteğini bir senaryo adımı olarak kaydedin. Ardından bu senaryoyu:

  • Dağıtım sonrası testlerde,
  • Koşullu akışlarda,
  • Zamanlanmış kontrollerde,
  • CI süreçlerinde

kullanabilirsiniz.

Adım zincirleme ve değer aktarımı için Apidog ile test senaryosu nasıl yazılır rehberine bakın. Gerekirse API test senaryolarında koşullu mantık ekleyebilir veya planlanmış API testleri ile senaryoyu zamanlayabilirsiniz.

Ancak burada önemli bir fark vardır: yerel bilgisayarınızda çalışan dosya yolu, başka bir ortamda otomatik olarak çalışmaz.

Kritik nokta: Yüklemeyi başka bir ortamda çalıştırmak

Apidog dosyanın kendisini değil, dosyanın yolunu saklar. Yerel bilgisayarınızda bu genellikle görünmez; çünkü yol gerçek dosyaya çözülür.

Örneğin:

/Users/jane/pics/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Bu yol yalnızca Jane'in bilgisayarında anlamlıdır. Aynı istek başka bir geliştirici, Runner veya CI ortamı tarafından çalıştırıldığında dosya bulunamaz.

Ekip çalışmasında sorun neden oluşur?

Ekip arkadaşınız isteği açtığında dosya alanını ve seçtiğiniz yolu görebilir. Ancak dosya kendi diskinde olmadığı için isteği gönderemez.

Çözüm:

  1. Dosyanın bir kopyasını ekip arkadaşınızın makinesine koyun.
  2. Dosya alanını o makinedeki geçerli yola yönlendirin.

Runner'da dosya yolu nasıl ayarlanır?

Runner, yalnızca dağıtım sırasında birime bağladığınız ana dizindeki dosyalara erişebilir. Bu bağlamayı -v bayrağıyla yaparsınız.

İzlenecek adımlar:

  1. Yükleme dosyasını Runner ana makinesindeki bağlı dizine kopyalayın.
  2. Senaryodaki dosya yükleme adımını açın.
  3. Sağ üstten Toplu Düzenleme seçeneğine tıklayın.
  4. Dosya alanının değerini Runner içindeki geçerli dosya yoluyla değiştirin.

Örnek:

/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Dosya bağlı dizinin altında değilse Runner bu dosyaya erişemez. Bu bir test senaryosu sınırlaması değil, dağıtım yapılandırması gereksinimidir.

CLI'da dosya yolu nasıl ayarlanır?

Aynı kural CLI için de geçerlidir:

  1. Dosyayı CLI'ın çalıştığı makineye koyun.
  2. Dosya alanındaki yolu o makinedeki gerçek konuma güncelleyin.

Örnek:

/opt/apidog/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Runner bağlama ve toplu düzenleme adımları için Apidog dosya yükleme istekleri belgelerine bakabilirsiniz.

Daha temiz çözüm: dosya yolunu değişkenle yönetin

Sabit dosya yolu yazmak yerine ortam değişkeni kullanın. Böylece senaryo aynı kalır; yalnızca ortamın değişken değeri değişir.

Örnek:

LOCAL_UPLOAD_FILE=/Users/jane/pics/jane-profile.png
RUNNER_UPLOAD_FILE=/opt/runner/jane-profile.png
Enter fullscreen mode Exit fullscreen mode

Dosya alanında sabit yol yerine bu değişkeni kullanın. Böylece:

  • Yerelde yerel dosya yolu,
  • Runner'da bağlı dizin yolu,
  • CI'da çalışma alanı yolu

kullanılabilir.

İş akışını Apidog CLI ile otomatikleştirin

Yükleme senaryonuz hazır olduğunda onu CI ortamında başsız olarak çalıştırabilirsiniz.

Önce CLI'ı kurun ve kimlik doğrulaması yapın:

npm install -g apidog-cli
apidog login --with-token <ERİŞİM_TOKENİNİZ>
Enter fullscreen mode Exit fullscreen mode

Ardından kaydedilmiş senaryoyu ortam kimliğiyle çalıştırın:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <senaryo_id> -e <ortam_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Parametreler:

  • -t: Test senaryosu kimliği
  • -e: Ortam kimliği
  • -r: Raporlayıcı türü

Birden fazla raporlayıcı kullanabilirsiniz:

-r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

CLI, bulut projesindeki kaydedilmiş senaryoları çalıştırır ve başarılı/başarısız sonucu işlem çıkış koduyla raporlar. Bu sayede CI işlem hattınızı test sonucuna göre durdurabilir veya devam ettirebilirsiniz. Kurulum detayları için Apidog CLI kurulum kılavuzunu inceleyin.

CLI çalıştırmasından önce dosyanın CLI makinesinde bulunduğunu ve senaryodaki yolun bu dosyayı gösterdiğini doğrulayın. Dosya yoksa veya yol geçersizse, diğer adımlar başarılı olsa bile yükleme adımı başarısız olur.

Satır başına veri geçirme gibi daha kapsamlı CI senaryoları için Apidog CLI ile veri odaklı test rehberine bakın.

SSS

Ekip arkadaşım neden dosya yükleme isteğimi gönderemiyor?

Apidog dosyayı değil, yerel dosya yolunu saklar. Ekip arkadaşınız sizin seçtiğiniz yolu görebilir, ancak bu yol kendi makinesindeki bir dosyaya karşılık gelmez. Dosyayı kendi bilgisayarına kopyalayıp alanı kendi yerel yoluna yönlendirmesi gerekir.

Aynı durum planlanmış testler ve Runner işleri için de geçerlidir: dosya, testin çalıştığı ortamda hazır olmalıdır.

Aynı istekte dosya ile JSON'u nasıl gönderirim?

Gövde türünü form-data olarak seçin:

  1. Dosya alanını file türüyle ekleyin.
  2. Başka bir alan ekleyin ve türünü string bırakın.
  3. JSON verisini bu string alanının değerine yapıştırın.

Sunucu dosyayı ve JSON metnini aynı çok parçalı istekte ayrı parçalar olarak alır.

Runner'da hangi dosya yolunu kullanmalıyım?

Runner birimine -v ile bağladığınız ana dizinin altındaki bir yol kullanın. Örneğin:

/opt/runner/dosyanız.jpg
Enter fullscreen mode Exit fullscreen mode

Dosyayı bu bağlı dizine kopyalayın ve senaryodaki alan değerini Toplu Düzenleme ile bu yola güncelleyin.

CLI tarafında benzer bir yol şöyle olabilir:

/opt/apidog/runner/dosyanız.jpg
Enter fullscreen mode Exit fullscreen mode

Dosya boyutu veya izin verilen türler için sınır var mı?

Apidog'un rolü isteği oluşturmak ve dosyayı belirtilen konumdan okumaktır. Gerçek dosya boyutu ve dosya türü sınırları test ettiğiniz API tarafından belirlenir.

Bu nedenle API'nizin:

  • Maksimum dosya boyutunu,
  • İzin verilen MIME türlerini,
  • Hatalı dosyalar için döndürdüğü yanıtları

kontrol edin ve reddedilen yüklemeler için de doğrulayıcılar ekleyin.

Yüklemelerde form-data mı, x-www-form-urlencoded mi kullanmalıyım?

Dosya gönderiyorsanız form-data kullanın. Bu seçenek multipart/form-data biçimine karşılık gelir ve dosya taşımak için tasarlanmıştır.

x-www-form-urlencoded, yalnızca dosya içermeyen kısa skaler alanlar için uygundur; PNG, JPEG veya PDF taşımaz.

Özet

Dosya yükleme testinde iki temel gereksinim vardır:

  1. multipart/form-data isteğini doğru oluşturmak
  2. Dosyanın testin çalıştığı her ortamda erişilebilir olduğundan emin olmak

Apidog'da gövdeyi form-data olarak ayarlayın, dosya alanının türünü file yapın, yerel dosyayı seçin ve yanıt doğrulayıcılarını ekleyin. JSON meta verisi gerekiyorsa bunu ayrı bir string alanında gönderin.

Senaryoyu Runner, CLI veya CI ortamına taşıdığınızda dosyayı ilgili makinede hazırlayın. Ardından yolu Toplu Düzenleme ile güncelleyin veya ortam değişkeni kullanın. Böylece otomatik test çalıştırmanız yerel çalıştırmanızla aynı davranır.

Kendi uç noktanızda denemek için Apidog'u indirin, yükleme rotanıza bir form-data isteği gönderin ve yanıt doğrulayıcılarını çalıştırın. Başlamak ücretsizdir, kredi kartı gerekmez.

Top comments (0)