Anda membuat endpoint yang menerima file. Pengguna mengunggah gambar profil ke POST /avatars, atau aplikasi Anda mengirim PDF yang ditandatangani ke POST /documents. Rute tersebut berfungsi di kepala Anda. Sekarang Anda perlu membuktikan bahwa itu berfungsi melalui HTTP: pilih file nyata, lampirkan ke bidang formulir, kirim permintaan, dan periksa responsnya.
Di sinilah banyak alat API menjadi rumit. Unggahan file menggunakan multipart/form-data, bukan JSON, sehingga Anda tidak dapat menempelkan body dan langsung mengirim. Anda memerlukan pembuat permintaan yang memahami bidang file, dan test runner yang dapat menemukan file saat pengujian berjalan nanti. Apidog menangani keduanya, dan panduan ini menjelaskan seluruh proses: mengirim satu unggahan, mengirim file bersama JSON, mengklaim respons, dan kemudian bagian jujur yang tidak ada yang memperingatkan Anda, yaitu apa yang terjadi ketika langkah unggahan yang sama berjalan tanpa kepala di Runner atau CLI dan tidak dapat menemukan file. Jika Anda ingin mengetahui latar belakang format itu sendiri terlebih dahulu, panduan awal unggah file di API mencakup cara struktur permintaan multipart. Referensi MDN tentang FormData adalah pendamping yang baik untuk sisi browser.
Apa itu multipart/form-data dan mengapa unggahan memerlukannya
Body permintaan API dapat memiliki beberapa bentuk. Di bagian Body permintaan Apidog, Anda dapat memilih form-data, x-www-form-urlencoded, JSON, XML, raw, atau binary. Sebagian besar waktu Anda menggunakan JSON. Unggahan file adalah pengecualian.
Tipe body form-data memetakan ke header Content-Type: multipart/form-data. Ini adalah format yang dibangun untuk mengunggah file bersama dengan data lainnya. Alih-alih satu blob, body dibagi menjadi beberapa bagian, masing-masing dengan nama dan kontennya sendiri. Satu bagian bisa berupa string biasa seperti keterangan, bagian lain bisa berupa byte mentah dari gambar. Itulah mengapa unggahan foto dan metadatanya dapat dikirim dalam permintaan yang sama.
Kerabat dekatnya adalah x-www-form-urlencoded. Ini terlihat serupa di editor, pasangan kunci-nilai dikirim dalam body, tetapi ini dimaksudkan untuk formulir sederhana tanpa file. Jika endpoint Anda menerima file, form-data adalah yang Anda inginkan. Gunakan x-www-form-urlencoded hanya ketika setiap bidang adalah skalar pendek dan tidak ada byte yang terlibat.
Dalam form-data, Apidog menampilkan setiap parameter sebagai pasangan kunci-nilai, dan setiap parameter memiliki tipe: string, integer, file, dan sebagainya. Tipe per-parameter itulah kuncinya. Atur bidang menjadi file dan Apidog memperlakukan nilainya sebagai file untuk dilampirkan daripada teks untuk dikirim.
Kirim unggahan file tunggal dan klaim responsnya
Misalnya Anda sedang menguji POST /avatars. Ini menerima satu bidang, avatar, yang berisi gambar, dan mengembalikan JSON dengan URL yang disimpan. Berikut adalah panduannya.
1. Buka bagian Body dan pilih form-data. Di endpoint Anda atau permintaan baru, atur metode ke POST dan URL ke rute avatar Anda. Buka tab Body dan pilih tipe body form-data. Apidog mengatur Content-Type: multipart/form-data untuk Anda.
2. Tambahkan parameter file dan atur tipenya ke file. Tambahkan parameter dengan kunci avatar. Di samping kunci, gunakan pemilih tipe untuk mengubah tipenya dari string ke file. Sel nilai akan berubah menjadi pemilih file alih-alih kotak teks.
3. Klik Unggah dan pilih file lokal. Klik Unggah pada baris avatar dan pilih gambar dari mesin Anda, misalnya jane-profile.png. Apidog mencatat jalur ke file tersebut.
4. Kirim permintaan. Tekan Kirim. Apidog membaca file dari jalur lokal yang disimpan, membangun body multipart, dan mengirimkannya. Penting untuk diketahui sebelumnya: Apidog mengirimkan file dalam permintaan tetapi tidak menyimpan file di cloud. Ini hanya menyimpan jalur lokal, bukan byte-nya. Detail itu penting nanti, jadi ingatlah.
Panggilan yang berhasil akan mengembalikan sesuatu seperti ini:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Klaim responsnya. Pengiriman yang mengembalikan 200 bukanlah tes yang berhasil dengan sendirinya. Tambahkan klaim agar pemeriksaan menjadi nyata. Di Apidog Anda menambahkan ini sebagai klaim pasca-permintaan pada endpoint atau langkah skenario. Secara sederhana Anda ingin mengonfirmasi status dan bahwa body membawa URL yang dapat digunakan:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Itu memetakan langsung ke UI klaim Apidog: satu klaim pada kode status, satu pada JSONPath $.avatarUrl yang ada, satu pada $.contentType. Jika Anda baru mengenal klaim, panduan klaim API menunjukkan seluruh set operator dan bagaimana JSONPath menargetkan bidang.
Untuk pemeriksaan realitas cepat di luar alat, unggahan yang sama di curl terlihat seperti ini:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
Flag -F adalah cara curl membangun bagian multipart, dan @ memberitahunya untuk membaca konten file. Parameter file form-data Apidog melakukan hal yang sama dengan pemilih alih-alih flag.
Kirim file dan JSON bersamaan
Endpoint nyata jarang hanya menerima file. POST /documents mungkin menginginkan file ditambah metadata: judul, kategori, mungkin array tag. Anda memiliki dua cara bersih untuk melakukan ini dalam satu permintaan multipart.
Kasus sederhana adalah bidang skalar. Tambahkan lebih banyak parameter form-data di samping bidang file Anda dan biarkan sebagai string atau integer. Sebuah string title, sebuah string category, sebuah file diatur ke tipe file. Ketiganya dikirim dalam permintaan yang sama.
Ketika metadata terstruktur, seperti objek bersarang atau array, Anda mengirimnya sebagai JSON di dalam bagian string. Tambahkan parameter form-data bernama metadata, biarkan tipenya sebagai string, dan tempelkan JSON langsung ke nilainya:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
Jadi permintaan memiliki dua bagian: file (tipe file) membawa q3-invoice.pdf, dan metadata (tipe string) membawa JSON tersebut. Server membaca file dari satu bagian dan menguraikan JSON dari bagian lainnya. Banyak API publik menerima unggahan persis dengan cara ini; dokumen unggahan file Stripe adalah contoh yang baik dari endpoint multipart nyata yang memasangkan bagian file dengan bidang biasa. Pola ini cukup umum sehingga pengguna Postman juga mengalaminya; jika Anda bermigrasi, panduan tentang mengunggah file dan data JSON di Postman memetakan dengan jelas ke bidang form-data Apidog.
Perlu melampirkan lebih dari satu file? Tambahkan parameter lain dengan tipe file. Sebuah POST /documents yang menerima file utama dan gambar mini akan mendapatkan dua baris file, file dan thumbnail, masing-masing dengan tombol Unggah-nya sendiri. Tidak ada mode multi-file khusus; Anda hanya perlu menambahkan parameter bertipe file sampai Anda mencakup setiap bagian yang diharapkan endpoint.
Ubah permintaan menjadi skenario uji yang dapat diulang
Satu kali pengiriman membuktikan endpoint berfungsi. Untuk menangkap regresi, Anda ingin unggahan berada di dalam skenario pengujian yang tersimpan yang berjalan sesuai permintaan atau sesuai jadwal. Rangkai langkah-langkahnya: unggah avatar, tangkap id yang dikembalikan, lalu panggil GET /users/{id} dan klaim URL avatar tetap ada.
Bangun ini dengan cara yang sama seperti Anda membangun satu permintaan, lalu simpan sebagai langkah dalam skenario. Panduan cara menulis skenario pengujian dengan Apidog mencakup perangkaian langkah dan meneruskan nilai antar langkah. Setelah unggahan berada dalam skenario, Anda dapat menjalankannya terhadap staging setiap deployment, menambahkan cabang bersyarat dengan logika bersyarat dalam skenario pengujian API, atau menempatkannya pada timer dengan pengujian API terjadwal.
Semua hal di atas berjalan dengan baik di mesin Anda, karena mesin Anda memiliki file tersebut. Asumsi itulah yang akan rusak selanjutnya.
Kesalahan: unggahan yang berjalan di tempat lain
Inilah bagian yang disembunyikan oleh jalur yang mudah. Apidog menyimpan jalur file, bukan file itu sendiri. Di laptop Anda, itu tidak terlihat, karena jalur tersebut selalu mengarah ke file nyata. Saat langkah yang sama berjalan di mesin yang berbeda, jalur tersebut tidak menunjuk ke apa pun.
Anda akan menemui ini di dua tempat.
Kolaborasi tim. Ketika seorang rekan tim membuka permintaan POST /avatars Anda, mereka melihat parameter file dan jalur yang Anda pilih, katakanlah /Users/jane/pics/jane-profile.png. Mereka dapat melihat permintaan, tetapi mereka tidak dapat mengirimnya, karena file tersebut berada di disk Anda, bukan di disk mereka. Jalur bersifat lokal ke mesin yang memilihnya.
Eksekusi Runner dan CLI. Inilah yang menjadi masalah dalam otomatisasi. Skenario unggahan Anda berhasil secara lokal, Anda menjadwalkannya di Runner atau menjalankannya dari CLI, dan langkah unggahan file gagal. Tidak ada yang salah dengan klaim Anda. Runner hanya tidak dapat menemukan file pada jalur yang disimpan oleh laptop Anda, karena jalur tersebut tidak ada di host runner.
Perbaikan mengikuti dari penyebabnya. File harus ada di mesin yang melakukan pengiriman, dan jalur langkah harus menunjuk ke sana.
Untuk Runner: Runner membaca file dari direktori host yang dipasang ke volumenya. Anda mengatur pemasangan itu saat Anda menerapkan Runner, menggunakan flag -v. Salin file unggahan Anda ke direktori host yang dipasang itu. Kemudian buka detail langkah unggahan file di skenario, klik tombol Batch Edit di sudut kanan atas, dan ganti nilai bidang file dengan jalur di dalam direktori Runner, misalnya:
/opt/runner/jane-profile.png
Untuk CLI: bentuk yang sama. Letakkan file di mesin CLI, lalu gunakan Batch Edit pada langkah tersebut untuk menunjuk jalur ke lokasinya di sana, misalnya:
/opt/apidog/runner/jane-profile.png
Lebih bersih dari hardcoding: gunakan variabel. Alih-alih menetapkan jalur literal dalam langkah, ganti nilai dengan variabel dan atur nilai variabel ke jalur file aktual per lingkungan. Kemudian skenario yang sama berjalan di laptop Anda, Runner, dan CI tanpa mengedit langkah setiap saat. Anda menunjuk variabel ke /Users/jane/pics/jane-profile.png secara lokal dan /opt/runner/jane-profile.png pada runner, dan langkah itu sendiri tidak pernah berubah.
Satu prasyarat yang patut dinyatakan dengan jelas: Runner hanya menjangkau file host yang berada di bawah direktori yang Anda pasang dengan -v pada saat deployment. Jika file Anda tidak berada di bawah pemasangan itu, tidak ada jalur yang akan menemukannya. Itu adalah detail pengaturan deployment, bukan batasan rencana. Dokumen Apidog tentang permintaan unggahan file menjelaskan langkah-langkah pemasangan dan pengeditan massal jika Anda menginginkan versi kanonik.
Otomatiskan alur kerja dengan Apidog CLI
Setelah skenario unggahan Anda disimpan, Anda dapat menjalankannya tanpa antarmuka pengguna di CI. Instal CLI dan autentikasi:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Kemudian jalankan skenario yang disimpan berdasarkan ID, menunjuknya ke lingkungan:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Di sini -t adalah ID skenario pengujian, -e adalah ID lingkungan, dan -r adalah reporter (gunakan cli, html, atau junit, dipisahkan koma untuk beberapa). CLI menjalankan skenario tersimpan Anda dari proyek cloud dan melaporkan keberhasilan/kegagalan dengan kode keluar, yang memungkinkannya mengontrol pipeline. Detail pengaturan tersedia di panduan instalasi Apidog CLI.
Satu peringatan jujur, dan itu sama dengan bagian terakhir: skenario dengan langkah unggah file memerlukan file yang ada di mesin CLI, dan jalur langkah harus menunjuk ke sana. Letakkan file di runner, lalu Batch Edit jalur (atau gunakan variabel) sebelum dijalankan. Lewati itu dan langkah unggah akan gagal menemukan file meskipun sisa skenario baik-baik saja. Untuk pengaturan CI yang lebih lengkap, termasuk meneruskan input per baris, lihat pengujian berbasis data dengan Apidog CLI.
FAQ
Mengapa rekan tim saya tidak dapat mengirim permintaan unggah file saya? Apidog menyimpan jalur file lokal, bukan file itu sendiri, dan tidak pernah mengunggah file ke cloud. Rekan tim Anda melihat permintaan dan jalur yang Anda pilih, tetapi jalur itu mengarah ke file di disk Anda, bukan di disk mereka. Mintalah mereka untuk menempatkan salinan file di mesin mereka dan menunjuk bidang ke jalur mereka sendiri. Mekanisme yang sama menjelaskan mengapa pengujian terjadwal dan tugas Runner memerlukan file yang disiapkan di tempat mereka berjalan.
Bagaimana cara mengirim JSON bersama dengan file dalam permintaan yang sama? Pertahankan tipe body sebagai form-data. Tambahkan bidang file Anda dengan tipe file, lalu tambahkan parameter lain dengan tipe string dan tempel JSON ke nilainya. Server akan mendapatkan kedua bagian dalam satu permintaan multipart: file dalam satu bagian, string JSON dalam bagian lain. Ini adalah cara standar untuk melampirkan metadata ke unggahan.
Jalur apa yang harus saya gunakan untuk file di Runner? Gunakan jalur di dalam direktori host yang Anda pasang ke volume Runner dengan flag -v pada saat deployment, misalnya /opt/runner/yourfile.jpg. Salin file ke direktori yang dipasang itu, lalu buka langkahnya, klik Batch Edit, dan atur nilai bidang ke jalur itu. Ekuivalen CLI terlihat seperti /opt/apidog/runner/yourfile.jpg.
Apakah ada batas ukuran file atau daftar tipe file yang diizinkan? Perilaku unggah di Apidog adalah tentang bagaimana permintaan dibangun dan dari mana file dibaca. Batas ukuran dan tipe aktual Anda berasal dari API yang Anda uji, jadi periksa aturan validasi server Anda sendiri dan tulis klaim terhadap respons yang dikembalikannya untuk file yang terlalu besar atau ditolak.
Haruskah saya menggunakan form-data atau x-www-form-urlencoded untuk unggahan? Gunakan form-data. Ini memetakan ke multipart/form-data dan dibangun untuk membawa file. x-www-form-urlencoded adalah untuk formulir sederhana dengan bidang skalar pendek tanpa file, jadi itu tidak akan membawa gambar atau PDF Anda.
Ringkasan
Pengujian unggahan file bermuara pada dua hal: membangun permintaan multipart dengan benar, dan memastikan file dapat dijangkau di mana pun pengujian berjalan. Di Apidog Anda mengatur Body ke form-data, mengubah tipe bidang Anda menjadi file, klik Upload, tambahkan JSON apa pun sebagai bagian string, lalu kirim dan klaim. Saat Anda memindahkan skenario yang sama ke Runner atau CLI, siapkan file di mesin itu dan arahkan ulang jalurnya dengan Batch Edit atau variabel, dan eksekusi otomatis akan berperilaku seperti eksekusi lokal Anda.
Ingin mencobanya di endpoint Anda sendiri? Unduh Apidog, arahkan permintaan form-data ke rute unggahan Anda, dan lihat responsnya kembali. Ini gratis untuk memulai, tidak memerlukan kartu kredit.