Cara Menguji Layanan Web SOAP dan WSDL di Apidog

Anda telah diberikan sebuah endpoint SOAP. Mungkin itu adalah konverter mata uang lama yang masih diandalkan oleh tim penagihan Anda, atau layanan web manajemen pesanan yang dijalankan oleh mitra di .NET. Anda perlu memanggilnya, memastikan ia mengembalikan apa yang dijanjikan kontrak, dan membuktikan bahwa ia tetap benar seiring perubahan kode di sekitarnya. Alat REST kurang cocok, karena SOAP menginginkan amplop XML lengkap, Content-Type tertentu, dan WSDL yang menjelaskan setiap operasi.

Apidog menangani permintaan SOAP dan WebService bersamaan dengan REST, GraphQL, dan gRPC, sehingga Anda tidak memerlukan aplikasi terpisah untuk satu layanan lama di tumpukan Anda. Panduan ini membahas kedua jalur yang didokumentasikan: mengirim permintaan SOAP secara manual, dan mengimpor WSDL sehingga Apidog membangun lingkungan dan endpoint untuk Anda. Jika Anda ingin gambaran protokol yang lebih luas terlebih dahulu, perbandingan kami mengenai REST, GraphQL, gRPC, dan SOAP menjelaskan di mana masing-masing mendapatkan tempatnya. Untuk definisi formal struktur amplop, spesifikasi W3C SOAP adalah sumber yang otoritatif.

Apa itu SOAP, dan mengapa ia membutuhkan penanganan yang berbeda

Apidog mendefinisikan SOAP sebagai Simple Object Access Protocol, sebuah protokol komunikasi berbasis XML yang memungkinkan berbagai platform dan bahasa pemrograman untuk berkomunikasi satu sama lain. Gagasan inilah yang menjelaskan mengapa banyak perusahaan masih menjalankannya. Klien Java dan layanan .NET dapat berkomunikasi melalui kontrak yang sama tanpa perlu memedulikan internal masing-masing.

Tiga properti penting saat Anda mengujinya. SOAP menggunakan XML untuk format pesan, sehingga setiap permintaan dan respons adalah dokumen terstruktur, bukan gumpalan JSON yang lepas. Jika XML itu sendiri adalah wilayah yang asing, referensi XML MDN adalah panduan dasar yang baik tentang sintaks yang akan Anda baca dan tulis. Biasanya ia bergerak melalui HTTP atau HTTPS, meskipun protokol ini mendukung yang lain. Dan ia mengikuti standar W3C untuk komunikasi yang terstruktur dan andal, itulah sebabnya bentuk pesan yang ketat dan aturan validasinya yang tegas.

Keketatan itulah alasan mengapa endpoint SOAP tetap digunakan untuk integrasi lintas platform, jembatan dari sistem lama ke modern, dan transaksi aman menggunakan WS-Security untuk pengiriman pesan terenkripsi dan terautentikasi. Itu juga mengapa Anda tidak bisa begitu saja mengirim permintaan bergaya REST ke sana. Anda memerlukan header yang tepat, body XML yang dibungkus dalam amplop SOAP, dan cara untuk membaca XML yang kembali. Jika Anda ingin melihat lebih dalam tentang bagaimana amplop dan isinya membawa data, lihat pembahasan kami tentang API SOAP dan XML.

Sebelum Anda memulai

Satu persyaratan penting menjadi dasar untuk semua yang di bawah ini. Untuk mengirim permintaan SOAP atau WebService, Apidog harus versi 2.1.31 atau lebih tinggi. Versi lama tidak mendukungnya. Buka Apidog, periksa versi Anda, dan perbarui jika Anda tertinggal. Semua hal lain dalam panduan ini mengasumsikan Anda menggunakan versi 2.1.31 atau lebih baru.

Jika Anda belum memiliki Apidog, unduh Apidog dan ikuti langkah-langkahnya. Coba gratis, tidak perlu kartu kredit.

Anda juga ingin memiliki detail layanan target Anda: URL endpoint, nama operasi yang ingin Anda panggil, dan parameter-parameternya. Jika Anda memiliki file WSDL, simpanlah di dekat Anda, karena bagian kedua dari panduan ini mengimpornya secara langsung.

Jalur A: Kirim permintaan SOAP secara manual

Ini adalah jalur ketika Anda memiliki endpoint dan mengetahui operasi yang ingin Anda panggil. Ada tiga hal yang Anda atur yang tidak diperlukan oleh permintaan REST, dan mengerjakannya dengan benar adalah inti dari pekerjaan ini.

Langkah 1: Atur header Content-Type secara manual

Permintaan SOAP tidak menyimpulkan headernya sendiri. Anda mengatur Content-Type sendiri, dan ada dua nilai yang valid:

• text/xml; charset=utf-8
• application/soap+xml

Yang mana yang benar tergantung pada layanan. Endpoint SOAP 1.1 biasanya mengharapkan text/xml; charset=utf-8, sedangkan endpoint SOAP 1.2 sering menginginkan application/soap+xml. Jika Anda tidak yakin, periksa WSDL atau dokumentasi layanan, dan jika nilai pertama mengembalikan kesalahan tentang jenis konten, beralihlah ke yang lain. Tambahkan header di bagian Headers permintaan sebelum Anda mengirim.

Langkah 2: Atur format body ke xml dan tempel amplop

Atur format Body permintaan ke xml, lalu tempelkan amplop SOAP. Amplop adalah dokumen dengan deklarasi namespace dan elemen Body yang menampung operasi yang Anda panggil, ditambah parameter apa pun yang tersarang di dalamnya.

Berikut adalah contoh yang dikerjakan terhadap layanan publik number-to-words, bentuk yang sama yang digunakan Apidog dalam dokumentasinya. Operasinya adalah NumberToWords dan ia mengambil satu parameter, ubiNum:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:web="http://www.dataaccess.com/webservicesserver/">
  <soap:Body>
    <web:NumberToWords>
      <web:ubiNum>1234</web:ubiNum>
    </web:NumberToWords>
  </soap:Body>
</soap:Envelope>

Namespace pada operasi harus cocok dengan apa yang diharapkan layanan, itulah sebabnya Anda membacanya dari WSDL daripada menebak-nebak. soap:Body membungkus panggilan sebenarnya; web:NumberToWords adalah operasi; web:ubiNum adalah input.

Langkah 3: Kirim dan baca respons XML

Kirim permintaannya. Respons kembali dalam XML, sebagai amplop SOAP yang Body-nya berisi operasi respons. Untuk panggilan di atas, Anda mendapatkan NumberToWordsResponse dengan hasil yang tersarang di dalamnya:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:NumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/">
      <m:NumberToWordsResult>one thousand two hundred and thirty four</m:NumberToWordsResult>
    </m:NumberToWordsResponse>
  </soap:Body>
</soap:Envelope>

Respons mencerminkan permintaan: nama operasi mendapatkan sufiks Response, dan nilainya berada di elemen hasil. Pencerminan itulah yang Anda klaim. Anda mengonfirmasi amplop kembali, node NumberToWordsResponse ada, dan hasilnya sesuai dengan yang Anda harapkan. Dokumentasi WebService khusus Apidog di webservice.apidog.io berisi referensi konfigurasi lengkap dan contoh amplop lainnya jika Anda ingin contoh kerja kedua.

Kasus penggunaan realistis mengikuti tiga langkah yang sama. Ganti NumberToWords dengan operasi ConvertCurrency pada layanan nilai tukar mata uang lama, lewatkan fromCurrency, toCurrency, dan amount sebagai elemen bersarang, dan baca angka yang dikonversi dari amplop respons. Atau panggil operasi GetOrderStatus pada layanan web pesanan, lewatkan orderId, dan pastikan node status yang dikembalikan. Mekanismenya tidak pernah berubah: header, body xml, kirim, baca amplop.

Jalur B: Impor WSDL untuk menghasilkan endpoint

Mengetik amplop secara manual bagus untuk satu panggilan. Ketika sebuah layanan mengekspos selusin operasi, biarkan WSDL yang melakukan pekerjaan itu. File WSDL menjelaskan setiap operasi, inputnya, dan alamat layanan, dan Apidog membaca semua itu dalam satu impor.

Berikut adalah jalur klik yang tepat:

1. Buka Pengaturan, lalu Impor Data.
2. Pilih WSDL.
3. Unggah file .wsdl atau .xml Anda.
4. Tinjau pratinjau endpoint API yang diurai Apidog dari file tersebut.
5. Buka tab Environments dan verifikasi bahwa alamat layanan sudah benar.
6. Klik Konfirmasi. Lingkungan yang diimpor dibuat secara otomatis.
7. Pilih lingkungan yang diimpor dari sudut kanan atas.
8. Kirim permintaan. Base URL diterapkan secara otomatis dari lingkungan tersebut.

Dua langkah dalam daftar itu adalah yang sering dilewati orang dan kemudian disesali.

Langkah 5 penting karena alamat layanan di WSDL adalah endpoint yang akan diakses oleh setiap permintaan yang diimpor. Jika itu menunjuk ke host staging, atau URL placeholder yang tidak pernah diperbarui oleh penulis WSDL, permintaan Anda akan menuju ke tempat yang salah. Periksa di tab Environments sebelum Anda mengklik Konfirmasi, bukan setelahnya.

Langkah 7 penting karena Base URL berada di lingkungan yang dibuat secara otomatis itu. Jika Anda tidak memilih lingkungan yang diimpor dari sudut kanan atas, permintaan Anda tidak memiliki alamat dasar dan akan gagal. Pilih terlebih dahulu, lalu kirim.

Setelah Anda mengimpor, setiap operasi muncul sebagai endpoint yang dapat Anda panggil tanpa menulis amplop sendiri, dan Anda melakukan penegasan pada respons XML persis seperti pada Jalur A. Jika Anda memindahkan seluruh proyek dari alat lain, panduan kami tentang mengimpor proyek SOAP mencakup migrasi dari awal hingga akhir.

Perhatikan satu batasan jujur: impor WSDL didokumentasikan untuk unggahan file .wsdl dan .xml. Mengimpor WSDL melalui URL atau dengan menempelkan isinya tidak didokumentasikan, jadi unggah file tersebut daripada mengharapkan kolom URL.

Beralih dari SoapUI

Jika pengujian SOAP Anda saat ini berada di SoapUI, Anda tidak perlu membangunnya kembali dari halaman kosong. Ekspor atau simpan WSDL Anda, impor ke Apidog dengan Jalur B, dan Anda akan mendapatkan operasi yang sama sebagai endpoint yang dapat dipanggil di dalam ruang kerja yang juga melakukan desain, mocking, dan dokumentasi. Keuntungannya adalah konsolidasi: satu proyek menampung layanan SOAP Anda, endpoint REST Anda, dan skenario pengujian Anda daripada menyebarkannya di berbagai alat terpisah. Perbandingan kami Apidog versus SoapUI menjelaskan apa yang dipertahankan dan di mana alur kerja berbeda.

Penegasan dan variasi

Satu panggilan yang berhasil membuktikan bahwa endpoint aktif. Sebuah pengujian membuktikan bahwa itu benar. Setelah permintaan SOAP Anda kembali, tambahkan penegasan pada amplop respons: konfirmasi bahwa node operasi respons yang diharapkan ada, ekstrak elemen hasil, dan periksa nilainya terhadap apa yang dijanjikan kontrak. Untuk layanan mata uang, Anda memastikan jumlah yang dikonversi adalah angka dalam rentang; untuk layanan pesanan, Anda memastikan status adalah salah satu nilai yang diizinkan.

Dari sana Anda membangun skenario pengujian yang dapat diulang yang merangkai panggilan, misalnya membuat pesanan, lalu menanyakan statusnya, meneruskan nilai di antara langkah-langkah. Panduan kami tentang menulis skenario pengujian dengan Apidog menunjukkan cara menghubungkan nilai yang diekstraksi ke permintaan selanjutnya. Pola ini agnostik protokol, sehingga skenario dapat mencampur panggilan SOAP dengan endpoint REST di sekitarnya.

Untuk endpoint yang aman, SOAP umumnya menggunakan WS-Security untuk pengiriman pesan terenkripsi dan terautentikasi. Header keamanan itu adalah bagian dari amplop SOAP yang Anda kirim, jadi Anda menambahkan blok keamanan wsse di dalam header amplop di samping operasi Anda. Mekanisme pengirimannya tetap sama: atur Content-Type, masukkan amplop lengkap termasuk header keamanan di body xml, lalu kirim.

Otomatiskan Alur Kerja dengan Apidog CLI

Setelah permintaan SOAP atau WSDL yang Anda impor disimpan sebagai skenario pengujian, Apidog CLI menjalankannya dari baris perintah sehingga pipeline dapat mengujinya pada setiap push. Instal dengan Node.js v16 atau yang lebih baru, lalu autentikasi:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Jalankan skenario tersimpan berdasarkan ID, terhadap lingkungan yang dibuat oleh impor WSDL Anda:

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 pelapor (cli, html, atau junit, dipisahkan koma untuk beberapa). Satu catatan jujur: dokumen mengonfirmasi bahwa runner mengeksekusi skenario dan suite pengujian yang disimpan, tetapi tidak menyatakan apakah skenario yang dibangun di atas langkah-langkah SOAP berjalan tanpa kepala (headless), jadi perlakukan CLI sebagai mesin Anda untuk skenario HTTP proyek dan untuk menjaga endpoint yang diimpor WSDL tetap sinkron di CI daripada mengasumsikan eksekusi khusus SOAP. Menghubungkannya ke pipeline dibahas dalam panduan CI/CD Apidog CLI kami.

FAQ

Content-Type mana yang harus saya gunakan untuk permintaan SOAP? Bisa text/xml; charset=utf-8 atau application/soap+xml. Yang tepat tergantung pada layanan: endpoint SOAP 1.1 umumnya mengharapkan yang pertama, endpoint SOAP 1.2 yang kedua. Atur secara manual di header permintaan, dan jika Anda mendapatkan kesalahan content-type, beralihlah ke nilai lain.

Apakah saya perlu paket berbayar untuk menguji SOAP di Apidog? Satu-satunya persyaratan yang didokumentasikan adalah Apidog versi 2.1.31 atau lebih tinggi. Tidak ada pembatasan tingkatan atau batasan self-hosted yang disebutkan untuk dukungan SOAP atau WSDL, jadi perbarui ke versi terbaru dan Anda siap.

Bisakah saya mengimpor WSDL dari URL? Impor WSDL yang didokumentasikan menerima unggahan file .wsdl dan .xml. Mengimpor melalui URL atau dengan menempelkan teks WSDL tidak didokumentasikan, jadi unggah filenya. Setelah diimpor, lingkungan dibuat secara otomatis dan Anda memilihnya dari sudut kanan atas sebelum mengirim.

Bagaimana cara menguji API SOAP dan REST dalam proyek yang sama? Apidog memperlakukannya sebagai jenis permintaan di dalam satu ruang kerja, sehingga satu proyek dapat menampung operasi SOAP di samping endpoint REST dan bahkan panggilan GraphQL. Jika GraphQL juga ada dalam daftar Anda, panduan kami tentang pengujian API GraphQL di Apidog membahas sisi itu, dan skenario pengujian dapat merangkai permintaan di antara semuanya.

Permintaan saya yang diimpor dari WSDL mengenai server yang salah. Apa yang terjadi? Dua penyebab umum. Entah alamat layanan di tab Environments salah saat waktu impor dan Anda mengklik Konfirmasi tanpa memeriksanya, atau Anda tidak memilih lingkungan yang diimpor dari sudut kanan atas, sehingga tidak ada Base URL yang diterapkan. Impor ulang dan verifikasi alamatnya, lalu pastikan lingkungan yang benar aktif sebelum Anda mengirim.

Ringkasan

Menguji SOAP tidak harus berarti alat lama yang terpisah. Di Apidog, Anda bisa mengirim amplop secara manual (atur Content-Type, atur body ke xml, tempel amplop, baca respons XML) atau mengimpor WSDL dan biarkan Apidog membangun endpoint dan lingkungan untuk Anda. Kedua jalur mengarah ke tempat yang sama: pemeriksaan berulang bahwa layanan web Anda masih menghormati kontraknya. Unduh Apidog versi 2.1.31 atau lebih tinggi, impor WSDL Anda, dan tempatkan layanan lama Anda di bawah pengujian yang sama dengan sisa permukaan API Anda.