Transcript SOAP vs REST - Joe Morrison

Dec 7, 2007
Can you read this? If not, please sit closer. Thank you.
XML RPC (1998)
Request
<?xml version="1.0"?>
<methodCall>
<methodName>doSomeWork</methodName>
<params>
<param>
<value><int>40</int></value>
</param>
<param>
<value><double>-12.53</double></value>
</param>
</params>
</methodCall>
Response
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value>
<array>
<data>
<value><dateTime.iso8601>19980717T14:08:55</dateTime.iso8601></value>
<value><string>Something here</string></value>
</data>
</array>
</value>
</param>
</params>
</methodResponse>
Early SOAP (2000) “section 5 encoding”
<?xml version="1.0"?>
<soap-env:envelope
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:header>
...
</soap-env:header>
<soap-env:body>
<m:doSomeWork xmlns:m="http://www.lab49.com/">
<foo xsi:type="xsd:int">40</foo>
<bar>-12.53</bar>
</m:doSomeWork>
</soap-env:body>
</soap-env:envelope>
<?xml version="1.0"?>
<soap-env:Envelope
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:body>
<m:doSomeWorkResponse xmlns:m="http://www.lab49.com/">
<soap-enc:array soap-enc:arrayType="xsd:ur-type[2]">
<baz xsi:type="xsd:int">12345</baz>
<quux xsi:type="xsd:string">Something here</quux>
</soap-enc:array>
</m:doSomeWorkResponse>
</soap-env:Body>
</soap-env:Envelope>
SOAP fancy encoding rules
References:
<e:Book>
<title>My Life and Work</title>
<author href="#Person-1"/>
</e:Book>
<e:Person id="Person-1">
<name>Henry Ford</name>
<address href="#Address-2"/>
</e:Person>
<e:Address id="Address-2">
<email>mailto:[email protected]</email>
<web>http://www.henryford.com</web>
</e:Address>
Sparse arrays:
<SOAP-ENC:Array SOAP-ENC:arrayType="xsd:string[,][4]">
<SOAP-ENC:Array href="#array-1" SOAP-ENC:position="[2]"/>
</SOAP-ENC:Array>
<SOAP-ENC:Array id="array-1" SOAP-ENC:arrayType="xsd:string[10,10]">
<item SOAP-ENC:position="[2,2]">Third row, third col</item>
<item SOAP-ENC:position="[7,2]">Eighth row, third col</item>
</SOAP-ENC:Array>
Document/literal (2003): Forget all the fancy encoding rules
<?xml version="1.0"?>
<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/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:header>
...
</soap-env:header>
<soap-env:body>
… your XML Schema compliant document goes here …
</soap-env:body>
</soap-env:envelope>
I want my, I want my RPC (rpc/literal)
<?xml version="1.0"?>
<soap-env:envelope
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:header>
...
</soap-env:header>
<soap-env:body>
<m:doSomething xmlns:m=“http://lab49.com/”>
<foo>
… XML Schema compliant value…
… XML Schema compliant value…
…
</foo>
<bar>
… XML Schema compliant value…
…
</bar>
</m:doSomething>
</soap-env:body>
</soap-env:envelope>
Namespace does not
have to be the same
as the parameter values
Argument elements don’t
even have a namespace
Lets you model procedure calls, but can’t validate SOAP body with an XML Schema
SOAP encoding convention line-up circa 2003
1.
RPC/encoded (the original)
2.
Document/literal (based on XML Schema, but doesn’t model RPC)
3.
RPC/literal (adds RPC modeling, breaks XML Schema validation)
Can’t we model RPC without breaking Schema validation?
Wrapped document literal style (2005)
<?xml version="1.0"?>
<soap-env:envelope
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<soap-env:header>
...
</soap-env:header>
<soap-env:body>
<m:doSomething xmlns:m=“http://lab49.com/”>
<m:foo>
…
Entire body complies with an XML Schema
</m:foo>
containing element doSomething containing
<m:bar>
a sequence of elements foo and bar
…
</m:bar>
</m:doSomething>
</soap-env:body>
</soap-env:envelope>
Handy summary
Scheme
Rating
Why?
rpc/encoded
(1998)
BAD
Because “encoded” means “section 5 encoding” and that hairy
scheme has been displaced by XML Schemas
doc/literal
(2003)
BEST
Send an XML Schema compliant document, get one back.
Awesome.
rpc/literal
(2003)
BAD
Failed attempt to reconcile document style with RPC.
wrapped/literal
(2005)
GOOD
Successful attempt to reconcile document style with RPC.
Web Service Definition Language (WSDL 1.1)
<definitions>
<types>
Wrapped style. Notice the operation
has one message part called “parameters”
which is an XML sequence of the args
<schema>
<element name="doSomething">
<complexType>
<sequence>
<element name="foo" nillable="true" type="string" />
<element name="bar" nillable="true" type="double" />
</sequence>
</complexType>
</element>
<element name="doSomethingResponse">
...
</element>
</schema>
</types>
<message name="doSomethingRequest"> <part name="parameters" element="doSomething"></part> </message>
<message name="doSomethingResponse"> <part name="parameters" element="doSomethingResponse"></part> </message>
<portType name="myServices">
<operation name="doSomething">
<input name="doSomethingRequest" message="doSomethingRequest"></input>
<output name="doSomethingResponse" message="doSomethingResponse"></output>
</operation>
</portType>
<binding name="myServicesHttpBinding" type="myServices">
<binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="doSomething">
<operation soapAction="" />
<input name="doSomethingRequest"> <body use="literal" /> </input>
<output name="doSomethingResponse"> <body use="literal" /> </output>
</operation>
</binding>
<service name="myServices">
<port name="myServicesHttpPort" binding="myServicesHttpBinding"> <address location="http://..." /> </port>
</service>
</definitions>
WSDL IS IMPORTANT
Code first / WSDL first decision algorithm
Will other projects
be using these
services? i.e. is this
part of an SOA?
No
Are you in a
great hurry?
Yes
Yes
Write code first in
wrapped/literal style, i.e. Use
annotations to name everything
and review WSDL afterward.
Write WSDL first.
Think through interfaces carefully, plan
for backward compatibility, write lots of
comments, and maintain in source control.
No
Write code first and
use doc/literal style.
i.e. Every method
has one arg. Use
annotations to name
everything and
review
WSDL afterward.
Goodies
• WS-Security (message integrity, confidentiality, and authentication)
• WS-ReliableMessaging
• WS-Routing (messaging patterns and routes)
• WS-Eventing (pub/sub)
• Many other incomprehensible extensions, collectively referred to as WS-*
The SOAP way of thinking
In the meantime…
Will SOAP collapse under its own weight?
Complexity
Low
High
SOAP
REST
?
Comparison points
• WSDL is a good idea for both SOAP and REST
(not a long-term differentiator)
• SOAP and REST both allow you to name resources with URIs
(also not a long-term differentiator)
• REST adds value to the entire web
(we don’t care)
• REST is easier to program
(not for long)
• SOAP provides better support for async messaging
• SOAP is better if developers and network administrators don’t
have a good relationship
In conclusion
For enterprise apps, default to SOAP.
But if (like Amazon.com) you
• are catering to people who are not making a large
investment in connecting to your service
• have control over your network
• are trying to reach a broad audience
… then go with REST.
Expires: Mon, 31 Mar 2008 20:00:00 GMT
Questions?