gedex’s blog

Melanjutkan tulisan sebelumnya, kali ini saya akan membahas tentang SOAP dan REST. Seperti halnya XML-RPC, SOAP juga memiliki standard mekanisme dalam pertukaran informasi menggunakan format XML. SOAP memiliki tiga bagian, yaitu:

• SOAP Envelope, yang mendefinisikan dokumen XML sebagai pesan SOAP. Element Envelope merupakan element root yang dapat menggunakan identifier namespace dari http://schemas.xmlsoap.org/soap/envelope/. Struktur dasar SOAP Envelope kurang lebih seperti berikut:

  <?xml version="1.0"?>
  <soap:envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingstyle="http://www.w3.org/2001/12/soap-encoding">
    ...
    Pesan informasi, bisa mengandung
    element Header dan harus
    terdapat element Body
    ...
  </soap:envelope>

  Element Envelope yang mendeklarasikan namespace (seperti di atas) harus menggunakan namespace-qualified untuk atribut tambahan lainnya (seperti soap:encodingStyle) serta sub-element-nya (opsional element <SOAP-ENV:Header> dan element <SOAP-ENV:Body> yang wajib ada). Penggunaan atribut encodingStyle bertujuan untuk mendefinisikan tipe data yang digunakan dalam dokumen. Atribut ini dapat muncul di element SOAP manapun, dan efeknya akan terkena ke konten element yang mendefinisikan atribut tersebut serta sub-element-nya.

• Aturan encoding SOAP, yang mendefinisikan mekanisme serialisasi pesan SOAP. Aturan serialisasi pada contoh di atas di identifikasikan oleh URI http://schemas.xmlsoap.org/soap/encoding/. Pesan SOAP yang menggunakan aturan serialisasi itu harus mendeklarasikan atribut encodingStyle dengan nilainya berisi URI http://schemas.xmlsoap.org/soap/encoding/.
• SOAP RPC, yaitu bagaimana SOAP dapat digunakan seperti halnya XML-RPC. Dalam SOAP sebenarnya dikenal 2 tipe aplikasi, yaitu RPC dan EDI (Electronic Document Exchange). SOAP RPC (atau lebih dikenal sebagai “RPC-style” SOAP) menggunakan pesan SOAP sebagai representasi nama prosedur berserta opsional parameternya dan nilai balik dari prosedur. SOAP EDI (atau dikenal sebagai “document-style” SOAP) merupakan pesan SOAP yang merepresentasikan transaksi bisnis seperti order pembelian, pembayaran pajak atau dokumen sejenis lainnya. Sebenarnya, semua Web Services yang saya bahas ini lebih ke RPC-style, yaitu bagaimana client merequest informasi terencoding berisi nama prosedur beserta parameternya yang ingin dipanggil dan server merespon nilai balik hasil eksekusi prosedur ke client. Saya akan berikan contoh bagaimana pesan RPC-style SOAP. Misalkan, server menyediakan fungsi hello($name) dimana nilai balik yang dihasilkan adalah string “hello $name” ($name adalah parameter bertipe string). Berikut contoh request dari client untuk pemanggilan fungsi hello dengan paramater “gedex”:

  POST /soap/server.php?debug=1 HTTP/1.0
  Host: localhost
  User-Agent: NuSOAP/0.7.3 (1.114)
  Content-Type: text/xml;
  charset=ISO-8859-1
  SOAPAction: ""
  Content-Length: 542
  
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>1</SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns3898:hello xmlns:ns3898="http://tempuri.org">
      <name xsi:type="xsd:string">gedex</name>
    </ns3898:hello>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

  Jika dilhat, pesan SOAP di atas menggunakan namespace-qualified SOAP-ENV (default dari nuSOAP) dan itu pun harus digunakan pada atribut serta sub-element-nya. Nama fungsi yang ingin dipanggil merupakan sub-element (yaitu <ns3898:hello>) dari element body (<SOAP-ENV:Body>) dan parameter nya merupakan konten dari sub-element hello (yaitu konten dari element <name>). Element <hello> menggunakan identifier namespace dari http://tempuri.org. Nah namespace ini juga berpengaruh kepada konten ataupun sub-elementnya (dengan begitu element <name> menggunakan namespace dari element parent-nya). Setelah server menganggap pesan SOAP client valid, dan eksekusi prosedur memberikan nilai balik, kini saatnya server memberikan response dalam pesan SOAP juga. Berikut contoh response pesan SOAP atas request di atas:

  HTTP/1.1 200 OK
  Date: Sun, 13 Apr 2008 08:12:07 GMT
  Server: Apache/2.2.8 (Win32) DAV/2 mod_ssl/2.2.8 OpenSSL/0.9.8g mod_autoindex_color PHP/5.2.5
  X-Powered-By: PHP/5.2.5 X-SOAP-Server: NuSOAP/0.7.3 (1.114)
  Content-Length: 6916
  Connection: close
  Content-Type: text/xml; charset=ISO-8859-1
  
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <ns1:helloResponse xmlns:ns1="http://tempuri.org">
      <return xsi:type="xsd:string">Hello gedex</return>
    </ns1:helloResponse>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>
  <!--
  2008-04-13 16:12:07.453128 soap_server: _SERVER is defined:
  ...
  
  debug data from nusoap_server ...
  
  ...
  -->

  Content-Length di atas cukup panjang, karena saya merequest nusoap_server (server.php) dengan ?debug=1, jadi server akan memberikan data debug dalam bentuk komentar. Nah, kita bisa lihat pesan SOAP dari response memberikan nilai balik dalam element <return> berisi “Hello gedex”. Bila Anda membaca posting saya sebelumnya mengenai XML-RPC, pasti Anda masih ingat bahwa response juga bisa mengembalikan <fault> jika ada error dalam payload XML-RPC yang mungkin bisa dari nama prosedur yang salah ataupun kesalahan parameter. Nah dalam SOAP, juga ada SOAP fault. Berikut contoh SOAP fault atas kesalahan pemanggilan nama prosedur:

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode xsi:type="xsd:string">SOAP-ENV:Client</faultcode>
      <faultactor xsi:type="xsd:string"></faultactor>
      <faultstring xsi:type="xsd:string">method 'halo' not defined in service</faultstring>
      <detail xsi:type="xsd:string"> ... panjang bay klo gw paste  ... </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

  SOAP fault terdiri atas 4 sub-element, yaitu faultcode, faultactor, faultstring dan detail. faultcode merupakan nilai yang dihasilkan untuk mengidentifikasi jenis kesalahan yang terjadi. Nilainya harus qualified-namespace (sebagaima kita lihat, yaitu SOAP-ENV:Client). Dalam namespace http://www.w3.org/2001/06/soap-envelope didefinisikan 4 standard faultcode, yaitu VersionMismatch, MustUnderstand, Server dan Client. Jika Anda masih bingung dengan istilah qualified-namespace, Anda bisa perhatikan bagaimana faultcode bertipe Client harus ditulis SOAP-ENV:Client mengikuti namespace element Envelope (SOAP-ENV:Envelope) yang telah didefinisikan sebelumnya. Keempat jenis faultcode tersebut dapat dikembangkan lebih jauh untuk memberikan tipe fault yang lebih ekspresif dan sempit, tapi tetap harus menjaga kompabilitas dengan core faultcode. Misal faultcode Client dapat memiliki turunan faultcode Client.Authentication untuk lebih mempersempit ekspresi fault (Client.Authentication menunjukkan terjadi kesalahan dalam authentifikasi si client, ya bisa dari salah password). Notasi “.” menunjukkan bahwa kata sebelah kiri “.” lebih generik dibanding kata yang di sebelah “.”. Akan sangat panjang jika saya bahas semua mengenai jenis fault. Jika Anda ingin membaca lebih lanjut mengenai spesifikasi SOAP, bisa baca catatan W3C mengenai SOAP 1.1. Perlu diketahui bahwa saya menggunakan library nuSOAP untuk contoh-contoh di atas, dan nuSOAP itu mengimplementasikan standard SOAP 1.1. Saat ini sudah ada spesifikasi SOAP 1.2

Sepertinya penjelasan singkat (sungguh, ini sangat singkat dan masih banyak definisi dan aturan SOAP yang belum bisa saya jabarkan di sini, baik dari keterbatasan pengetahuan saya dan kemalasan saya) ini akan masih banyak meninggalkan tanda tanya, yang insyaAllah tanda tanya tersebut bisa dijawab oleh W3C dan google :). Sepertinya pembahasan mengenai REST saya sambung ke bagian 3. Basically, posting yang terlalu panjang akan membuat pembaca muak sebelum membaca, karena begitulah saya :p, dan jika dibuat estafet akan lebih asyik dan membuat pembaca (yang dapat menarik kesimpulan tentunya) merasa penasaran menunggu lanjutannya. Sengaja saya tidak pakai tag read more, agar pembaca blog ini yang menggunakan aggregator atau RSS Reader dapat menarik (feed) konten secara keseluruhan.

Referensi:

• Simple Object Access Protocol (SOAP) 1.1
• Soap tutorial di W3Schools.com
• NuSOAP - Web Services Toolkit for PHP
• Programming Web Applications with SOAP