Belajar SOAP - WS-Policy & Service Versioning

#Pendahuluan

Setelah di episode 9 kita menangani keandalan, sekarang kita bahas dua hal yang menentukan masa depan service: WS-Policy (bagaimana service menyatakan kemampuannya) dan versioning (bagaimana service berevolusi tanpa merusak konsumen).

Mengapa penting? Dalam integrasi B2B, service SOAP tidak di-upgrade sendirian — konsumennya adalah sistem milik perusahaan lain yang kadang masih memakai versi lama bertahun-tahun. Kebijakan yang tidak didokumentasikan memaksa integrasi menebak-nebak; versioning yang sembrono memutus sistem di tengah malam. Keduanya adalah disiplin, bukan sekadar teknik.

#WS-Policy: Menyatakan Kemampuan Service

WS-Policy adalah cara mendeklarasikan kebijakan (keamanan, transport, reliability) secara machine-readable, bisa dilampirkan ke elemen WSDL. Alih-alih mengarahkan konsumen membaca dokumentasi, policy memberitahu tool client apa yang dibutuhkan.

#Assertion Dasar

Policy adalah kumpulan assertion — pernyataan tentang kemampuan atau kebutuhan:

Policy dasar

<wsp:Policy xmlns:wsp="http://www.w3.org/ns/ws-policy"
  xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:TransportBinding>
        <sp:TransportToken>
          <sp:HttpsToken RequireClientCertificate="false"/>
        </sp:TransportToken>
      </sp:TransportBinding>
      <sp:Wss11/>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

ExactlyOne berarti "pilih salah satu dari alternatif ini"; All berarti "semua assertion ini wajib". Di contoh di atas: transport wajib HTTPS dan memakai WS-Security 1.1.

#Policy di dalam WSDL

Policy dilampirkan ke WSDL dengan elemen wsp:PolicyReference:

PolicyReference di binding

<definitions xmlns:wsp="http://www.w3.org/ns/ws-policy" ...>
  <wsp:Policy wsu:Id="BankPolicy">
    <!-- assertion keamanan di atas -->
  </wsp:Policy>
 
  <binding name="BankBinding" type="tns:BankPortType">
    <wsp:PolicyReference URI="#BankPolicy"/>
    <soap:binding style="document"
      transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getBalance">
      <soap:operation soapAction=""/>
      <input><soap:body use="literal"/></input>
      <output><soap:body use="literal"/></output>
    </operation>
  </binding>
</definitions>

Client yang mendukung WS-Policy (CXF, WCF, Metro) membaca ini dan otomatis mengonfigurasi dirinya — misalnya menambahkan header keamanan atau memakai HTTPS. Inilah awal dari WS-SecurityPolicy, yang akan kita bangun penuh di episode 15.

Tip

Policy adalah kontrak yang sama wajibnya dengan tipe data. Kalau policy berubah (mis. tiba-tiba butuh token X.509), konsumen yang lama tidak akan bisa berbicara — itu perubahan breaking, setara menambah field wajib di request. Selalu hitung dampaknya seperti versioning.

#Service Versioning

#Aturan Emas

Versi kontrak adalah bagian dari namespace, bukan sekadar field di dalam pesan. Ketika kontrak berubah, namespace baru dibuka — sehingga pesan versi lama dan baru bisa hidup berdampingan dalam satu service. Pola namespace:

Versi 1: urn:example:bank:1
Versi 2: urn:example:bank:2

Setiap versi punya WSDL dan endpoint sendiri; konsumen memilih berdasarkan versi yang mereka pahami.

#Perubahan Kompatibel vs Breaking

Bukan semua perubahan membutuhkan versi baru. Klasifikasikan perubahan dengan disiplin:

Perubahan	Sifat	Contoh
Menambah elemen opsional	Kompatibel	Field `nickname` opsional
Menambah operasi baru	Kompatibel	`transfer` di samping `getBalance`
Menambah elemen wajib	Breaking	`accountNo` jadi wajib
Menghapus elemen	Breaking	`balance` dihapus
Mengubah tipe/format	Breaking	`string` jadi `decimal`
Mengubah urutan `sequence`	Breaking	Memindahkan posisi elemen
Mengubah namespace	Breaking	`urn:example:bank` → `urn:example:bank:2`

Aturan sederhananya: jika client lama akan mengirim/menerima sesuatu yang membuat pesan invalid, itu breaking. Kalau ragu, anggap breaking — membuat versi baru selalu lebih murah daripada merusak integrasi mitra.

#Strategi Deprecation

Saat versi baru lahir, versi lama tidak langsung mati. Pola yang menghormati konsumen legacy:

Ekspos versi baru di endpoint baru — http://svc/bank/v2 berdampingan dengan http://svc/bank/v1.
Tandai versi lama sebagai deprecated di WSDL — konsumen bisa melihat peringatannya.
Sediakan jendela transisi — minimal 6-12 bulan di lingkungan B2B, dengan komunikasi formal ke mitra.
Log penggunaan versi lama — data untuk memutuskan kapan versi lama bisa dipensiunkan.
Matikan versi lama bertahap — mulai dari error di operasi tertentu, lalu full shutdown, dengan tanggal yang diumumkan jauh hari.

Menandai deprecated di WSDL

<wsdl:documentation>
  DEPRECATED: gunakan endpoint /v2.
  Batas akhir dukungan: 2027-12-31.
</wsdl:documentation>

Warning

Jangan pernah "mendaur ulang" namespace lama dengan kontrak baru. Konsumen yang menyimpan WSDL versi lama akan diam-diam memanggil kontrak baru — bug paling berbahaya karena tidak menghasilkan error apa pun, hanya hasil yang salah.

#Pola Praktis: Endpoint dan Kontrak

Ringkasan pola yang bisa langsung diterapkan:

Aspek	Pola disarankan
Namespace	`urn:example:bank:2` — versi di namespace, bukan di URL saja
Endpoint	`/bank/v1`, `/bank/v2` — URL stabil per versi
Deprecation	Dokumentasi di WSDL + jadwal transisi formal
Backward compat	Jangan ubah field existing; hanya tambah yang opsional
Konsumen legacy	Selalu beri jendela transisi sebelum mematikan versi

#Penutup

Inti yang harus dibawa pulang:

WS-Policy mendeklarasikan kemampuan service secara machine-readable dan bisa dilampirkan ke WSDL.
ExactlyOne = pilih satu; All = semua wajib; policy yang berubah bisa jadi perubahan breaking.
Versi kontrak hidup di namespace; perubahan breaking membuka namespace baru.
Tambah field opsional/operasi baru = kompatibel; hapus/wajibkan/ubah tipe = breaking.
Deprecation butuh jendela transisi dan log penggunaan — jangan matikan mendadak.

Di episode 11 selanjutnya kita akan membahas MTOM dan attachment — mengoptimalkan transmisi file biner lewat XOP/MTOM dengan DataHandler, upload-download dokumen via SOAP, dan perbandingannya dengan SOAP with Attachments (SwA). Sampai jumpa di episode 11!