Belajar SOAP - Konsep Dasar & Arsitektur Utama

#Pendahuluan

Setelah di episode 1 kita memahami sejarah dan alasan SOAP bertahan, pada episode ini kita masuk ke inti teknisnya: struktur dan arsitektur pesan SOAP. Inilah fondasi yang akan kalian pakai terus — dari episode 3 (WSDL) sampai episode 22 (refleksi akhir).

Mengapa struktur ini penting? Karena SOAP adalah protokol dengan aturan ketat: server menolak pesan yang struktur atau namespace-nya salah. Tidak seperti JSON yang bebas bentuk, envelope SOAP punya anatomi yang sudah dibakukan. Kalian harus hafal anatomi ini di luar kepala sebelum menyentuh tool apa pun.

#Anatomi Envelope

Setiap pesan SOAP adalah dokumen XML dengan satu elemen root bernama Envelope yang berisi tiga bagian opsional-wajib berikut:

Contoh lengkap envelope SOAP 1.2:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Header>
    <m:transaction xmlns:m="urn:example:meta" soap:mustUnderstand="1">
      7f3a9c
    </m:transaction>
  </soap:Header>
  <soap:Body>
    <tns:getBalance xmlns:tns="urn:example:bank">
      <tns:accountNo>ACC-001</tns:accountNo>
    </tns:getBalance>
  </soap:Body>
</soap:Envelope>

Perhatikan tiga hal di contoh ini:

1. Namespace SOAP — SOAP 1.2 memakai http://www.w3.org/2003/05/soap-envelope; SOAP 1.1 memakai http://schemas.xmlsoap.org/soap/envelope/. Keduanya berbeda dan tidak bisa dicampur.
2. Header dengan mustUnderstand — receiver yang tidak paham elemen bertanda mustUnderstand="1" wajib menolak pesan. Ini mekanisme SOAP untuk evolusi fitur secara aman.
3. Body berisi payload bisnis — elemen request di dalam body memakai namespace bisnis sendiri (urn:example:bank), bukan namespace SOAP.

#Header: Rumah Metadata

Header adalah bagian paling fleksibel dari SOAP. Di sinilah berbagai spesifikasi WS-* menyimpan datanya:

• WS-Security — token autentikasi, tanda tangan digital, enkripsi (episode 14-15).
• WS-Addressing — alamat reply, action, message ID (episode 9).
• WS-ReliableMessaging — sequence number untuk jaminan pengiriman (episode 9).
• Transaction context — correlation ID agar request yang melintasi beberapa service bisa dilacak (episode 13).

Header bersifat opsional tetapi powerful: ia memisahkan transport plumbing dari payload bisnis, sehingga middleware (gateway, ESB) bisa membaca dan menambah header tanpa menyentuh isi body.

#Body: Payload Request-Response

Body berisi data bisnis yang dikirim antara client dan server. Bentuknya ditentukan oleh WSDL: untuk operasi request-response, satu elemen body berisi elemen request, dan response datang dengan elemen jawaban. Contoh response untuk request di atas:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <tns:getBalanceResponse xmlns:tns="urn:example:bank">
      <tns:balance currency="IDR">2750000</tns:balance>
    </tns:getBalanceResponse>
  </soap:Body>
</soap:Envelope>

Perhatikan pola penamaan getBalance → getBalanceResponse: ini konvensi WSDL yang otomatis dipakai oleh tool generator seperti JAX-WS.

#Fault: Error Standar

Ketika operasi gagal, SOAP tidak mengembalikan halaman HTML error — ia mengembalikan elemen Fault di dalam body dengan kode dan detail standar:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <soap:Fault>
      <soap:Code>
        <soap:Value>soap:Receiver</soap:Value>
      </soap:Code>
      <soap:Reason>
        <soap:Text xml:lang="id">Akun tidak ditemukan</soap:Text>
      </soap:Reason>
      <soap:Detail>
        <e:error xmlns:e="urn:example:bank">ACC-001 tidak dikenal</e:error>
      </soap:Detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Detail lengkap faultcode, perbedaan SOAP 1.1 vs 1.2, dan strategi error mapping akan dibahas di episode 8.

#Model Transport dan Alur Pesan

SOAP adalah protokol yang transport-agnostic: pesan bisa melintasi HTTP, HTTPS, SMTP, bahkan message queue. Praktik dominan adalah SOAP over HTTP, di mana service di-post ke satu endpoint dan balasan datang sebagai HTTP response:

Karena setiap pesan membawa seluruh konteks (header + body) di satu dokumen, SOAP disebut stateless di level transport: server tidak perlu menyimpan sesi antara dua request — cukup satu round-trip untuk satu operasi lengkap.

#Peran WSDL sebagai Kontrak

Di atas arsitektur pesan berdiri WSDL — deskripsi machine-readable yang "menjual" service ke dunia: operasi apa yang tersedia, tipe data apa yang dipakai, di endpoint mana, dan bagaimana pesannya dibentuk. Analoginya: jika envelope adalah amplopnya, WSDL adalah buku petunjuk pengiriman lengkapnya. Tanpa WSDL, client tidak bisa membangun request yang valid. Kita bedah WSDL secara penuh di episode 3.

#Penutup

Inti yang harus dibawa pulang:

• Envelope punya tiga bagian: Envelope (root), Header (metadata opsional), dan Body (payload + fault).
• Namespace SOAP berbeda antara 1.1 dan 1.2 — mencampurnya akan membuat pesan ditolak.
• mustUnderstand="1" memaksa receiver menolak header yang tidak ia pahami — mekanisme evolusi fitur.
• Fault adalah mekanisme error standar SOAP, bukan halaman error HTML.
• SOAP berjalan di atas HTTP/HTTPS/SMTP; WSDL adalah kontrak yang mendefinisikan operasi dan tipe data.

Di episode 3 selanjutnya kita akan membedah WSDL sebagai kontrak layanan — struktur types, message, portType, binding, dan service, plus perbandingan pendekatan contract-first vs code-first. Sampai jumpa di episode 3!