Architecting Web Services

Architecting Web Services Lorna Mitchell, Ibuildings

About Me

PHP Developer/Consultant/Trainer with Ibuildings
PHP community evangelist
Blog at http://lornajane.net

Web Services

Provide information in machine-readable format
For local or remote consumption
For consumption by discrete/modular systems

Why Web Services

Service Types

RPC (Remote Procedure Call)
SOAP
REST (REpresentational State Transfer)

RPC

All URLs point to a single endpoint
Parameters give method names
Request body can take a variety of formats

RPC Advantages

RPC is a great format for wrapping existing functionality
Can abstract between existing systems
Familiar functional paradigm

RPC Example Flickr's XML-RPC Request <methodCall> <methodName> flickr.test.echo </methodName> <params> <param><value><struct> <member> <name> name </name> <value><string> value </string></value> </member> <member> <name> name2 </name> <value><string> value2 </string></value> </member> </struct></value></param> </params> </methodCall>

RPC Example Flickr's XML-RPC Response <?xml version="1.0" encoding="utf-8" ?> <methodResponse> <params> <param> <value> <string> [escaped-xml-payload] </string> </value> </param> </params> </methodResponse>

Delivering RPC

Consumers will need

Service URL
Docs of functions and arguments
If this was an existing system, existing docs may suffice

SOAP

Special case of RPC using XML
Has given formats for messages and errors
Libraries exist for creating server and client in most languages

PHP SOAP Server Example require_once('lib/myClass.php'); ini_set("soap.wsdl_cache_enabled", "0"); $server = new SoapServer("service.wsdl"); $server->setClass("MyClass"); $server->handle();

PHP SOAP Client Example ini_set('soap.wsdl_cache_enabled','0'); require_once('lib/Snapshot.php'); $wsdl = "Service.wsdl"; $client = new SoapClient($wsdl, $params); $output = $client->requestShot( 'http://www.php.net','', 300, 400);

WSDL

Web Service Description Language
Widely used with SOAP
Describes the methods, arguments and data types available
IDEs can read this and hint
Validity of requests is checked before they are sent

WSDL <?xml version ='1.0' encoding ='UTF-8' ?> <definitions name='MyClass' targetNamespace='urn:MyClassInventory' xmlns:tns='urn:MyClassInventory' xmlns:soap=' http://schemas.xmlsoap.org/wsdl/soap/ ' xmlns:xsd=' http://www.w3.org/2001/XMLSchema ' xmlns:soapenc=' http://schemas.xmlsoap.org/soap/encoding/ ' xmlns:wsdl=' http://schemas.xmlsoap.org/wsdl/ ' xmlns='http://schemas.xmlsoap.org/wsdl/'> <message name='getAccountStatusRequest'> <part name='accountID' type='xsd:string'/> </message> <message name='getAccountStatusResponse'> <part name='accountID' type='xsd:string'/> <part name='counter' type='xsd:float' /> </message> <portType name='MyClassPortType'> <operation name='getAccountStatus'> <input message='tns:getAccountStatusRequest'/> <output message='tns:getAccountStatusResponse'/> </operation> </portType> <binding name='MyClassBinding' type='tns:MyClassPortType'> <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/> <operation name='getAccountStatus'> <soap:operation soapAction='urn:xmethods-delayed-quotes#getAccountStatus'/> <input> <soap:body use='encoded' namespace='urn:xmethods-delayed-quotes' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/> </input> <output> <soap:body use='encoded' namespace='urn:xmethods-delayed-quotes' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/> </output> </operation> </binding> <service name='MyClassService'> <port name='MyClassPort' binding='tns:MyClassBinding'> <soap:address location='http://rivendell.local:10002/MyClassServiceServer.php'/> </port> </service> </definitions>

Delivering SOAP

In WSDL mode, only the WSDL needs to be supplied
Otherwise method names, arguments and types will be needed

REST

A series of concepts
Generally uses HTTP (HyperText Transfer Protocol)
URLs are resource locations
Verbs tell the service what to do
Status codes indicate what the outcome was

Implementing REST

Standard application architecture
Routing to map requests to internal functionality
Output not always HTML

REST Examples

GET http://example.com/users/lorna
POST http://example.com/users
PUT http://example.com/users/lorna
GET http://example.com/users

Delivering REST

Full documentation including URL formats, data types, and response formats
Must include information about error handling

REST as an inspiration

RESTful is a strict definition
REST is full of great ideas
REST is great for clean, simple, robust services
Cherry-pick the bits that work

Just don't call it "RESTful" :)

General Architecture Considerations

Machine-Readable Formats 1111011110101000001101011011110001001101011111011000101010001011010100001110110111101001111110011100110010100110011000111100011000000111100000011001001101000001011100101101011011100010010111000001111010000100100010010101010101110110000000100101101110100000111001000010100010011111111010001010110000010100000101011000001000000100110000100100110010101001110101100001010110001111000101110111011110010011110101101100110111100111101000001010100100110111001111111010000000000111000000011101000000010011001101100110000101011111010100111011100100000000111010010110100011110110111000011100000010111010010011111011001001010110111011111101110000011111100010010000011010100010010011100000111111101100111111000001000100101011011100001101111011100010101010011000000100011011010000111010000000001100010011011011010010000101110111110110111101110111000111010100001001101011010101110101010100111000010110001110001111001011100011110100000110100110000000100011101011010010011100111011001111111011111000011101000111100110

Machine-Readable Formats

XML (eXtensible Markup Language)
JSON (JavaScript Object Notation)
Key/value pairs
Form variables

Background: XML <menu id="file" value="File"> <popup> <menuitem value="New" onclick="CreateNewDoc()" /> <menuitem value="Open" onclick="OpenDoc()" /> <menuitem value="Close" onclick="CloseDoc()" /> </popup> </menu>

Background: JSON {"menu": { "id": "file", "value": "File", "popup": { "menuitem": [ {"value": "New", "onclick": "CreateNewDoc()"}, {"value": "Open", "onclick": "OpenDoc()"}, {"value": "Close", "onclick": "CloseDoc()"} ] } }}

Choosing Formats

XML needed for SOAP, widely supported in most languages
JSON easier for JavaScript, use with AJAX-esque requests
Or make both available
Use built-in libraries for your platform

Error Handling

Will you ignore extra fields? Error?
How about incorrect data types? Cast or reject?
Make error messages meaningful and unique

Asynchronous Handling

Consider swift response and offline processing
Manage job queues and retries
Will users poll for a change?
Could implement callbacks

Versions and Formats

Include as parameters to your service:

The service version (allows for future upgrades)
The preferred response format

Building Blocks

Some frameworks have functionality built-in for services
Can be convenient
Consider performance

Resources

RESTful Web Services – Leonard Richardson and Sam Ruby
http://uk.php.net/sca
http://benramsey.com
http://lornajane.net

WSDL: Service <service name='MyClassService'> <port name='MyClassPort' binding='tns:MyClassBinding'> <soap:address location='http://rivendell.local:10002/MyClassServiceServer.php'/> </port> </service>

WSDL: Binding <binding name='MyClassBinding' type='tns:MyClassPortType'> <soap:binding style='rpc' transport='http://schemas.xmlsoap.org/soap/http'/> <operation name='getAccountStatus'> <soap:operation soapAction='urn:xmethods-delayed-quotes#getAccountStatus'/> <input> <soap:body use='encoded' namespace='urn:xmethods-delayed-quotes' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/> </input> <output> <soap:body use='encoded' namespace='urn:xmethods-delayed-quotes' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'/> </output> </operation> </binding>

WSDL: Port Type <portType name='MyClassPortType'> <operation name='getAccountStatus'> <input message='tns:getAccountStatusRequest'/> <output message='tns:getAccountStatusResponse'/> </operation> </portType>

WSDL: Message <message name='getAccountStatusRequest'> <part name='accountID' type='xsd:string'/> </message> <message name='getAccountStatusResponse'> <part name='accountID' type='xsd:string'/> <part name='counter' type='xsd:float' /> </message>