gedex’s blog

He.. sekarang saya akan membahas mengenai REST. Sebenarnya kalau dilihat ada beberapa tulisan saya di bagian sebelumnya yang perlu direvisi, misalnya: pada Bagian I, saya menulis “…tentang SOAP dan REST saya tulis nanti di webservices bagian 2…“. Dan ada lagi, di bagian II, saya menulis “kali ini saya akan membahas tentang SOAP dan REST“. Tapi kenyataannya, saya pisah postingan SOAP dan REST, atau bahkan nanti bisa saja ini berlanjut ke bagian IV, hehe.. Mau tahu alasannya:

1. Saya tidak suka 1 postingan itu terlihat begitu panjang. Posting yang panjang hanya membuat pembaca malas membaca secara keseluruhan. Karena menurut survey pada 1 orang (yaitu saya sendiri), tulisan yang panjang hanya akan dibaca paragraf awal dan akhir saja.
2. Saya malas merevisi jika itu bukan kesalahan typo dan grammar yang fatal, yang bisa menyebabkan salah pengartian (biasanya komentator yang peduli akan memberikan feedback). Kesalahan yang saya sebutkan di atas tidak tergolong kesalahan typo dan grammar yang fatal, dan lagi jika potongan post di baca secara terurut pasti pembaca akan tahu sebabnya.
3. Nah, inilah style menulis saya. Menulis A di paragraf awal dan memberi kesimpulan Z di akhir paragraf.

Pembahasan singkat REST sepertinya akan lebih banyak meninggalkan tanda tanya, karena ini lebih abstrak dibanding RPC-Style. Sebelumnya, saya akan membalik lagi ke postingan sebelumnya mengenai SOAP. Ada beberapa point yang tertinggal mengenai SOAP, yaitu mengenai arsitektur dasar Web Services (WS) yang meliputi pertukaran pesan / informasi, pendeskripsian WS dan publishing & discovering deskripsi WS. Ada 3 peranan dalam arsitektur WS ini, yaitu service requesters, service discovery agency dan service providers. Service provider mengimplementasikan web service dan mendefinisikan deskripsi servicenya ke requestor atau service discovery agency. Interaksi antara 3 pemeran WS ini meliputi 3 operasi, yaitu: publish, find dan bind. Pertama-tama requestor menggunakan operasi find untuk mendapatkan deskripsi service (bisa dari service discovery agency) dan menggunakan deskripsi itu mem-bind (memetakan) dirinya dengan service provider dan kini requestor dapat mengeksekusi (invoke) atau juga berinteraksi dengan service yang disediakan. Disini deskripsi service bisa berupa file WSDL (Web Services Definition Language) yang dipublish oleh service providers yang menjelaskan bagaimana requestor menggunakan pesan SOAP yang benar agar dapat berinteraksi dengan WS providers. Nah muncul lagi deh teknologi WSDL yang mungkin masih jadi tanda tanya bagi Anda. Penjelasan lebih lanjut mengenai arsitektur WS dan bagaimana teknologi SOAP, WSDL, HTTP berperan di dalamnya bisa Anda baca di W3C Working Draft mengenai Web Services Architecture.

Read the rest of this entry »

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

Dua postingan sebelumnya saya tulis menggunakan Weblog Client yang dapat mensupport XML-RPC Client dari Wordpress (WP). Kebanyakan pengguna WP masih menggunakan administrasi web-based hanya untuk sekedar menulis post / page. Jika Anda yang memiliki kebanyakan ide (tapi sulit koneksi inet) yang jika dituangkan dalam tulisan cukup panjang, coba deh gunakan Weblog Client untuk menyimpan draft tulisan Anda secara lokal, dan publish sekiranya sudah matang. Lalu apa sih sebenarnya XML-RPC itu? Apakah termasuk ke dalam Web Services? Lalu apa untungnya Web Services itu sendiri bagi end-user dan developer?

Saya akan bahas secara singkat 3 teknologi terkait Web Services, yaitu XML-RPC, SOAP dan REST-based Web Services. Nah yang terakhir (REST - Respresentational State Transfer) itu, bukanlah spesifikasi standard seperti halnya XML-RPC dan SOAP, tapi desain dan style arsitektural dari arsitektur software berbasis network. Kita akan lihat nantinya seperti apa implementasi REST.
Rangkuman apa itu Web Services akan saya bahas di bagian kedua, setelah selesai penjelasan Web Services saya akan memberikan contoh implementasi Web Services (XML-RPC, SOAP dan REST-based) menggunakan PHP.

OK, kita mulai dengan XML-RPC (XML Remote Procudure Calling). XML-RPC merupakan spesifikasi dan kumpulan implementasi yang membuat software yang berjalan pada sistem operasi berbeda, lingkungan berbeda dapat membuat pemanggilan prosedur melalui internet. XML-RPC menggunakan HTTP sebagai media transportasi dan XML (eXtensible Markup Language) sebagai encoding pesan. XML-RPC didesain sesedarhana mungkin dalam mentransmit struktur data yang kompleks, memprosesnya dan mengembalikannya. Struktur data yang menggunakan encoding XML merupakan badan request HTTP-POST dari client. Cara paling mudah memahami XML-RPC adalah dengan melihat proses mulai dari request ke server, lalu bagaimana server menerjemahkan pesan (parsing) berformat XML, bagaimana server mendapatkan pesan client yang sudah di parsing ternyata.. katakanlah merequest prosedur jumlah(x, y), kemudian server mengeksekusi prosedur jumlah(x, y) dan hasilnya (misal hasil jumlah x + y) di encode XML lalu di kembalikan ke client sebagai response dari request-nya. Saya mengasumsikan bahwa Anda mengenal XML (Rekomendasi XML) dan spesifikasi HTTP (RFC2616) . Berikut contoh request XML-RPC:

POST /xml-rpc/server.php HTTP/1.0
Host: localhost
Content-Type: text/xml
User-Agent: The Incutio XML-RPC PHP Library
Content-length: 196

<?xml version="1.0"?>
<methodcall>
    <methodname>demo.addTwoNumbers</methodname>
    <params>
        <param>
            <value>
                <int>2</int>
            </value>
        </param>
        <param>
            <value>
                <int>3</int>
            </value>
        </param>
    </params>
</methodcall>

Bagian paling atas adalah HTTP Accept request-header (lihat RFC2616), dimana dalam spesifikasi XML-RPC harus didefinisikan dalam sebuah request. Baris paling atas di bagian header adalah URI, dimana saya merequest (POST) script (server.php) pada path server (/xml-rpc). Baris Host: merupakan server yang saya request (localhost), Content-Type: harus text/xml, User-Agent: berisi string yang menjadi identitas client (saya menggunakan library dari IXR untuk implementasi client XML-RPC) dan Content-Length: adalah panjang konten pesan (bisa tebak satuannya? Itu adalah panjang string. Karena saya menggunakan library IXR, semua pesan header sudah otomatis diperhitungkan secara valid). Setelah header adalah payload (konten yang menjadi pesan bagi server) berformat XML dan harus berisi satu struktur <methodcall> beserta sub-item bersarang lainnya. Format payload, strukturnya, tag-nya dan tipe nilai yang memenuhi spesifikasi standard XML-RPC bisa dibaca di halaman spesifikasi XML-RPC. Setelah server menerima request dan menerima format payload XML-RPC yang valid dan eksekusi prosedur addTwoNumbers memberikan nilai balik, maka saatnya server meng-encode hasilnya dalam XML dan memberikan response atas request dari client. Berikut contoh response dari server:

HTTP/1.x 200 OK
Date: Sat, 12 Apr 2008 03:59:15 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
Content-Length: 155
Connection: close
Content-Type: text/xml

<?xml version="1.0"?>
<methodResponse>
    <params>
        <param>
            <value>
                <int>5</int>
            </value>
        </param>
    </params>
</methodResponse>
</pre>

Nah server juga harus mengembalikan format response sesuai dengan spesifikasi XML-RPC. Jika tidak ada error, server akan memberikan status code 200, Content-Type: harus text/xml, Content-Length harus ada dan benar. Badan response adalah XML dengan satu struktur <methodResponse> yang mengandung satu <params> yang mengandung satu <param> yang mengandung satu <value>. Selain bisa mengandung <params>, <methodResponse> juga bisa mengandung satu <fault> yang mengandung satu <value> bertipe <struct> mengandung dua element, satu bernama <faultCode> beritipe <int> dan satu lagi bernama <faultString> bertipe <string>. <fault> digunakan untuk merespon nilai balik terhadap tidak suksesnya eksekusi prosedur yang diinginkan, bisa dari parameter yang salah atau nama prosedur yang salah. OK, kesimpulannya XML-RPC adalah teknologi Web Services yang paling sederhana dan mudah dimengerti. Tujuan awal dibentuknya protokol XML-RPC adalah portabilitas di antara lingkungan yang berbeda, tidak perlu ada penanganan khusus dalam interface CGI dan bila ada firewall, cukup pantau request POST dengan Content-Type text/xml.

Yang kedua adalah SOAP (Simple Object Access Protocol). SOAP adalah protokol berbasis XML yang digunakan untuk pertukaran informasi antara aplikasi melalui HTTP/HTTPS, bahkan SMTP. Awalnya SOAP di kembangkan atas sokongan Microsoft, tapi kemudian di ajukan ke W3C. Untuk lebih lanjut tentang SOAP dan REST saya tulis nanti di Web Services bagian 2, karena kalau ditumpuk jadi satu pasti bacanya jadi malas sampai habis :).

Daftar referensi:

• XML-RPC Home Page
• XML-RPC Specification
• The Incutio XML-RPC Library for PHP