Belajar SOAP - WSDL: Kontrak Layanan

#Pendahuluan

Setelah di episode 2 kita memahami anatomi envelope, sekarang kita mempelajari pasangan wajibnya: WSDL (Web Services Description Language). Jika envelope adalah amplopnya, WSDL adalah kontraknya — dokumen yang mendefinisikan apa yang bisa dipanggil, dengan tipe data apa, dan di endpoint mana.

Mengapa WSDL begitu penting? Karena inilah yang membuat SOAP berbeda dari REST. Di REST, kontrak sering berupa dokumentasi informal. Di SOAP, kontrak bersifat machine-readable: tool generator membaca WSDL lalu membangkitkan client atau server secara otomatis. Perbedaan interpretasi kontrak adalah sumber utama masalah integrasi B2B — dan WSDL adalah alat untuk menghilangkannya.

#Struktur Dasar WSDL 1.1

WSDL 1.1 — versi yang mendominasi industri via WS-I Basic Profile — punya lima elemen utama dalam satu dokumen:

Contoh WSDL minimal untuk service getBalance:

<?xml version="1.0" encoding="UTF-8"?>
<definitions
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:tns="urn:example:bank"
  targetNamespace="urn:example:bank"
  name="BankService">
 
  <types>
    <xsd:schema targetNamespace="urn:example:bank">
      <xsd:element name="getBalance">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="accountNo" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="getBalanceResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="balance" type="xsd:decimal"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>
 
  <message name="GetBalanceRequest">
    <part name="parameters" element="tns:getBalance"/>
  </message>
  <message name="GetBalanceResponse">
    <part name="parameters" element="tns:getBalanceResponse"/>
  </message>
 
  <portType name="BankPortType">
    <operation name="getBalance">
      <input message="tns:GetBalanceRequest"/>
      <output message="tns:GetBalanceResponse"/>
    </operation>
  </portType>
 
  <binding name="BankBinding" type="tns:BankPortType">
    <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>
 
  <service name="BankService">
    <port name="BankPort" binding="tns:BankBinding">
      <soap:address location="http://localhost:8080/bank"/>
    </port>
  </service>
</definitions>

Alur membacanya: service menunjuk ke binding → binding menunjuk ke portType → portType memakai message → message memakai elemen di types. Satu dokumen, satu alur naratif lengkap.

#styles dan use: document-literal vs rpc-encoded

Pada soap:binding, ada dua atribut yang menentukan bentuk pesan:

Praktik modern dan WS-I Basic Profile menuntut document-literal: body persis mengikuti skema XSD, tanpa layer encoding tambahan. Sebagian besar tool (JAX-WS, .NET, PHP) menghasilkan WSDL document-literal secara default.

#Dua Pendekatan Pengembangan

#Contract-First

Kalian menulis WSDL (dan XSD-nya) dulu, lalu generate kode server dan client dari WSDL.

• Kelebihan: kontrak menjadi sumber kebenaran tunggal; tim integrasi bisa mendiskusikan kontrak sebelum implementasi; versioning lebih terkontrol; interoperabilitas lintas bahasa lebih terjaga.
• Kekurangan: kurva belajar XSD/WSDL lebih curam; butuh tooling (mis. wsdl2java dari CXF atau dotnet-svcutil).
• Cocok untuk: integrasi B2B antarsistem, kontrak antarperusahaan yang wajib disepakati dulu.

#Code-First

Kalian menulis kode Java/PHP/C# dulu, lalu tool membangkitan WSDL dari anotasi/atribut di kode.

• Kelebihan: cepat untuk prototype; satu sumber (kode) untuk logika dan kontrak; tooling otomatis (JAX-WS @WebService, WCF atribut).
• Kekurangan: WSDL hasil generate bisa berubah tak terduga saat kode berubah; kontrak "terikat" ke implementasi; sulit membangun kontrak yang disepakati antarperusahaan.
• Cocok untuk: service internal, prototype, single-vendor deployment.

#Common Pitfalls WSDL

Beberapa kesalahan yang paling sering merusak integrasi:

• Mencampur namespace SOAP — binding memakai SOAP 1.1 tapi envelope yang dikirim SOAP 1.2 (atau sebaliknya).
• targetNamespace salah — elemen yang diharapkan di namespace bisnis ternyata berada di namespace default.
• use="encoded" di integrasi lintas stack — banyak tool modern menolak atau menghasilkan hasil tak terduga.
• Mengedit WSDL dengan tangan tanpa re-generate — drif kontrak vs kode, penyebab bug klasik code-first.
• Lupa soapAction — sebagian server menolak request yang soapAction-nya tidak cocok dengan binding.

#Penutup

Inti yang harus dibawa pulang:

• WSDL punya lima bagian: types, message, portType, binding, service — mengalir dari abstrak ke konkret.
• Document-literal adalah gaya standar WS-I; rpc-encoded hanya untuk legacy.
• Contract-first menulis WSDL dulu (stabil untuk B2B); code-first men-generate WSDL dari kode (cepat untuk prototype).
• Kesalahan namespace dan gaya binding adalah penyebab masalah integrasi paling umum.

Di episode 4 selanjutnya kita akan praktik nyata pertama: membuat service SOAP di Java dengan JAX-WS — dari anotasi @WebService dan @WebMethod, publishing endpoint, hingga generate client dengan wsimport. Sampai jumpa di episode 4!