WS-*/REST Web Services with WSO2 WSF/PHP Samisa Abeysinghe Nandika Jayawardana Zend PHP Conference & Expo, San Jose, 30 Oct 2006
About Us Samisa Member ASF Lead contributor Apache Axis2/C Was an active contributor Apache Axis C++ Software architect at WSO2 Developer WSO2 WSF/PHP Visiting lecturer University of Moratuwa Nandika Committer Apache Axis2/C Software engineer at WSO2 Developer WSO2 WSF/PHP
From PHP Axis2 to WSO2 WSF/PHP PHP Axis2 effort initially started in PECL Latest code at wso2.net http://www.wso2.net/projects/wsf/php
WSO2 WSF/PHP WSO2 Web Services Framework/PHP Open source with Apache license Is available as a PHP extension Based on WSO2 WSF/C Uses Apache Axis2/C Supports consuming and providing Web services Mainly using WS-* stack REST is also possible WSO2 WSF/PHP is a PHP extension for providing and consuming Web Services"
Why Yet Another SOAP Extension? WSO2 WSF/PHP supports more SOAP 1.1 SOAP 1.2 MTOM WS-Addressing WS-Security UsernameToken And more to come WS-Reliable Messaging WS-Security full support (encryption/signature) WS-Eventing WSDL generation/proxy generation/data binding
WSO2 WSF/PHP Agenda
Agenda (1 of 3) Installation Quick Start Consuming Google Spell Check Service Hello Service/Client Math Service/Client API Object Oriented Functional Providing Services In-out Operations
Agenda (2 of 3) Providing Services In-only operations Consuming Service Out-in Operations Out-Only Operations Using SOAP SOAP 1.1 vs. SOAP 1.2 Using REST Payload Formats String, SimpleXMLElemnt, domdocument
Agenda (3 of 3) Attachments with XOP/MTOM Optimized vs Non-Optimized Uploading Downloading WS-Addressing WS-Security UsernameToken Sending UsernameToken (client) Verifying UsernameToken (service) Notes Next Steps
WSO2 WSF/PHP Installation
Installation Requirements PHP 5.1.1 or above libxml2 For Linux we have the source distribution For windows, we have both binary and source distributions Please have a look at the install guide
WSO2 WSF/PHP Quick Start
Quick Start Spell checking with Google spell check Endpoint: http://api.google.com/search/beta2 Google spell uses SOAP 1.1 Request payload Google key (you need to get one) Word to spell check (e.g. tamperature) Response payload Correct word (e.g. Temperature)
Hello Sample Hello service with greet operation Client would consume this service Request and response payloads: Request: <greet> Hello Service! <greet> Response: <greetresponse> Hello Client! <greetresponse>
Hello Service - Steps Write the function corresponding to the greet operation of the service Create a WSService giving the operation map along with options Call the reply() method of the WSService class That would invoke the operation and prepare the response
Hello Client - Steps Create a WSMessage instance with desired request payload and options Create a WSClient instance Send the request and receive the response Consume the response
Math Sample Handling string payloads is easy Can I do math? Convert the payload into an easy to process format Then process the payload
WSO2 WSF/PHP The API
WSO2 WSF/PHP The Big Picture PHP Userland SAPI Layer Zend Engine WSO2 WSF/PHP Extension WSO2 WSF/C (SOAP Engine)
WSO2 WSF/PHP API Object oriented WSClient WSService WSMessage WSFault Functions ws_request ws_send ws_reply
Providing Services A service can have multiple operations Each operation should have a corresponding function that implements the operation Syntax: WSMessage user_defined_operation(wsmessage payload) Example: function echofunction($inmessage){ $returnmessage = new WSMessage($inMessage->str); return $returnmessage; }
Providing Services : In-Out MEP In-Out message exchange pattern Operation takes in a request payload and returns a response payload e.g. echofunction shown earlier It returns a message
Providing Services : In-Only MEP In-Only message exchange pattern Operation takes in a request payload but does not return anything e.g. notifyfunction function notifyfunction($inmessage) { return; } It does not return anything
Providing Services Operation Map (1 of 2) Need to specify What operations are supported by the service What functions implement those operations Examples: from hello service: $service = new WSService(array("operations" => array("greet"))) from echo service: $service = new WSService(array("operations" => array("echostring" => "echofunction")))
Providing Services Operation Map (2 of 2) Difference? $service = new WSService(array("operations" => array("greet"))) Operation name and the function name are the same, that is greet $service = new WSService(array("operations" => array("echostring" => "echofunction"))) Operation name and function name are different Operation is echostring Function name is echofunction Significance of operation name?
Providing Services Operation Name Web services engine would resolve the operation to be invoked by looking at the local name of the first child element of the request payload When WS-Addressing is not in use
Providing Services WSService->reply() reply() method Triggers processing of the request Calls required functions as necessary Prepares response payload to be returned to client
Providing Services Function API ws_reply() Need to include wsf.php include_once('./wsf.php') Simple API to provide services ws_reply(array("operations" => array("echostring" => "echofunction"))); OO equivalent $service = new WSService(array("operations" => array("echostring" => "echofunction"))); $service->reply();
Consuming Services Minimum requirements Request payload Service endpoint address
Consuming Services : Out-In MEP Out-In message exchange pattern Sends s request payload expecting a response payload e.g. echo client $client = new WSClient(array("to" => "http://localhost/zend_tute/echo_service.php")); $resmessage = $client->request($reqpayloadstring)
Consuming Services : Out-Only MEP Out-Only message exchange pattern Sends a request payload and does not expect a response e.g. notify client $client = new WSClient(array("to" => "http://localhost/zend_tute/notify_service.php")); $client->send($reqpayloadstring)
Consuming Services Function API (1 of 2) Need to include wsf.php include_once('./wsf.php') ws_request() $resmessage = ws_request($reqpayloadstring, array("to"=>"http://localhost/zend_tute/reply_echo_se rvice.php")); OO equivalent $client = new WSClient(array("to" => "http://localhost/zend_tute/echo_service.php")); $resmessage = $client->request($reqpayloadstring);
Consuming Services Function API (2 of 2) ws_send() ws_send($reqpayloadstring, array("to"=>"http://localhost/zend_tute/notify_servic e.php")); OO equivalent $client = new WSClient(array("to" => "http://localhost/zend_tute/notify_service.php")); $client->send($reqpayloadstring);
WSO2 WSF/PHP SOAP and REST
Using SOAP Can select version using usesoap option Default is SOAP 1.2 SOAP 1.2 usesoap => TRUE 1.2 1.2 SOAP 1.1 usesoap => 1.1 1.1 REST usesoap => FALSE
Identifying SOAP Version from SOAP Message Namespace: SOAP 1.1: http://schemas.xmlsoap.org/soap/envelope/ SOAP 1.2: http://www.w3.org/2003/05/soap-envelope Content-Type: SOAP 1.1: text/xml SOAP 1.2: application/soap+xml
Using REST Disable SOAP usesoap => FALSE Sends message payload as it is Can select HTTP method to be used "HTTPMethod" => POST GET Default is POST
Payload Formats Function API takes any of String SimpleXMLElement DomDocument Payload is based on XML-in / XML-out processing model
WSO2 WSF/PHP XOP/MTOM (Attachments)
Binary Attachments Binary Data Images, sounds files, video files Not worth transforming to XML Using the QoS capabilities of WS-* with binary data e.g. Secure reliable connection
Opaque Non-XML Data - Problem Users want to leverage the structured, extensible markup conventions of XML Don t want to abandon existing data formats Needs existing formats to coexist with XML & to be treated as opaque sequences of octets by XML tools and infrastructure
Opaque Non-XML Data - Solution Two approaches By value By Reference
By Value (1 of 2) Embedding encoded texts of opaque data in the XML payload Base64 encoding HexBinary encoding
By Value (2 of 2) Advantages Ability to process and describe data based on XML component of the data Disadvantages Bloating of the size 1.33x with Base64, 2x with HexBinary Processing overhead
Example of By Value <soap:body> <m:data xmlns:m='http://example.org/stuff'> <m:photo xmlmime:contenttype='image/png > /awkkapggyq= </m:photo> <m:sig xmlmime:contenttype='application/pkcs7- signature> Faa7vROi2VQ= </m:sig> </m:data> </soap:body> </soap:envelope>
By Reference (1 of 2) Attaching pure binary data as external unparsed entities outside of the XML document Use of packaging mechanisms MIME Embedding reference URI's to those entities, inside XML payload
By Reference (2 of 2) Advantages No encodings used Efficient Disadvantages Two data models One for XML One for attachments
XOP XML Optimized Packaging XOP package A serialization of the XML Infoset inside an extensible packaging format Attached binary content appears as if it is in-line (by value) Actual attachment goes outside message (by reference)
MTOM SOAP Message Transmission Optimization Mechanism Describes how XOP is layered in to SOAP/HTTP Presents an XML Infoset to the SOAP application MIME multipart/related
MTOM Optimized SOAP Message Content-Type: multipart/related; boundary=mime_boundary; type="application/xop+xml"; start="<0.1b@wso2.org>"; start-info="text/xml; charset=utf-8" --MIME_Boundary content-type: application/xop+xml;charset=utf-8; type="application/soap+xml;" content-transfer-encoding: binary content-id: <0.1B@wso2.org> <?xml version='1.0?><soapenv:envelope...>... <xop:include href="cid:1.80@wso2.org" xmlns:xop=http://www.w3.org/2004/08/xop/include/>... </soapenv:envelope> --MIME_Boundary content-type: application/octet-stream content-transfer-encoding: binary content-id: <1.80@wso2.org> Binary Data... --MIME_Boundary--
Sending an Attachment Include a reference in request payload to indicate where the attachment should go Create outgoing message with an attachment array containing content ID to binary content map Enable MTOM "usemtom" => TRUE
Receiving an Attachment On client, set responsexop => TRUE On service, set requestxop => TRUE When respective XOP property is TRUE, received message would have two properties set attachments (cid key to binary string value map) cid2contenttype (cid key to attachment content type map)
Sending Optimized vs Non-Optimized Optimized "usemtom" => TRUE Non-Optimized "usemtom" => FALSE
WSO2 WSF/PHP WS-Addressing
WS-Addressing WS-Addressing provides mechanisms to address Web services and messages Two versions; both supported version 1.0 submission
Enabling WS-Addressing on Service Set WS-Addressing action mapping for operations Example: $operations = array("echostring" => "echofunction"); $actions = array("http://php.wsf.wso2.net/samples/echostring" => "echostring"); $service = new WSService(array("operations" => $operations, "actions" => $actions))
Using WS-Addressing on Client Two basic requirements Set WSA action Set usewsa option Example: $reqmessage = new WSMessage($reqPayloadString, array("to" => "http://localhost/echo_service_addr.php", "action" => "http://php.wsf.wso2.net/samples/echostring")); $client = new WSClient(array("useWSA" => TRUE))
Addressing Version Can select version using usewsa option Default is FALSE, that means WSA is not used If client uses WSA, then service too will use WSA No need to explicitly enable on service Version 1.0 usewsa => TRUE 1.0 1.0 Submission usewsa => "submission"
Identifying WSA Version from SOAP Message Namespace: Version 1.0: http://www.w3.org/2005/08/addressing Submission: http://schemas.xmlsoap.org/ws/2004/08/addressing
WSO2 WSF/PHP WS-Security UsernameToken
WS-Security UsernameToken Two forms Plain text password Digest of password Request message Security header contains UsernameToken element with the Username Password child elements Service can verify them and authenticate
WS-Security in Service Have to enable security "secure"=>true Also need to set up password file Default location: /usr/local/apache2/passwd/passwords Can set wsf.passwd_location in php.ini File format user:password
WS-Security in Client Security will be enabled if both user and password options are set "user"=> username "password"=> password
WS-Security UsernameToken More Options Digest Password "digest" => TRUE Time-stamp "timestamp" => TRUE Time to Live "timetolive" => 5m
WSO2 WSF/PHP Notes
Options Precedence Options on client side WSMessage level WSClient level Message level options take precedence over client level Options on services Can be only set on WSService
Log File Log is written to /tmp/wsf.log by default Can set the location of the log in php.ini wsf.log_path=path_to_log Name of the log file is wsf.log always Useful when debugging SOAP engine
Future Plans WS Reliable Messaging Work in progress WS Security Encryption work in progress Signing will take some time (C14N) WSDL Generating for given service Proxy for given WSDL and data binding
Project Information Project home: http://www.wso2.net/projects/wsf/php Mailing list: wsf-php-user@lists.wso2.com To subscribe: mailto:wsf-php-user-request@lists.wso2.com?subject=subscribe This project is open source with Apache license You are welcome to send feedback and contribute
References WSO2 WSF/PHP SOAP REST MTOM API document: http://www.wso2.net/project/wsf/php/1.0alpha1/docs/api.html Manual: http://www.wso2.net/project/wsf/php/1.0alpha1/docs/manual.html SOAP 1.1: http://www.w3.org/tr/2000/note-soap-20000508/ SOAP 1.2: http://www.w3.org/tr/soap12-part1/ http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.w3.org/tr/soap12-mtom/ WS-Addressing Version 1.0: http://www.w3.org/2002/ws/addr/ Submission: http://www.w3.org/submission/ws-addressing/ WS-Security http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf