Sunday, May 8, 2011

WSDL SOAP bindings confusion - RPC vs document

What is the difference between RPC and document styles in SOAP web services?

I was asked this question at a job interview and was embarrassed to discover that I didn't know the answer (considering that I listed "SOAP web services" on my resume). I've heard the terms before, but couldn't remember what they meant. The main difference lies in what the body of the SOAP message looks like.

RPC vs document styles

The body of an RPC (remote procedure call) style SOAP message is constructed in a specific way, which is defined in the SOAP standard. It is built around the assumption that you want to call the web service just like you would call a normal function or method that is part of your application code. The message body contains an XML element for each "parameter" of the method. These parameter elements are wrapped in an XML element which contains the name of the method that is being called. The response returns a single value (encoded in XML), just like a programmatic method. The WSDL code for a RPC-style web service is less complex than that of a document-style web service, but this isn't a big deal since WSDLs aren't meant to be handled by humans.

A RPC-style request:
    <multiply>    <!-- web method name -->
      <a>2.0</a>  <!-- first parameter -->
      <b>7</b>    <!-- second parameter -->

A document style web service, on the other hand, contains no restrictions for how the SOAP body must be constructed. It allows you to include whatever XML data you want and also to include a schema for this XML. This means that the client's and server's application code must do the marshalling and unmarshalling work. This contrasts with RPC in which the marshalling/unmarshalling process is part of the standard, so presumably should be handled by whatever SOAP library you are using. The WSDL code for a document-style web service is much more complex than that of a RPC-style web service, but this isn't a big deal since WSDLs aren't meant to be handled by humans.

A document-style request:
    <!-- arbitrary XML -->
    <movies xmlns="">
        <title>2001: A Space Odyssey</title>
        <title>Donnie Darko</title>

The main downside of the RPC style is that it is tightly coupled to the application code (that is, if you decide you want to call these web methods like normal methods--this is not a requirement, but this is what the RPC style was designed for). This means that if you want to change the order of the parmeters or change the types of those parameters, this change will affect the definition of the web service itself (just as it would affect the definition of a normal function or method).

Document style services do not have this issue because they are loosely coupled with the application code--the application must handle the marshalling and unmarshalling of the XML data separately. For example, with a document style service, it doesn't matter if the programmer decides to use a "float" instead of an "int" to represent a particular parameter because it's all converted to XML text in the end.

The main downside of the document style is that there is no standard way of determining which method of the web service the request is for. It's easy to get around this limitation, but, however it's done, it must be done manually by the application code. (Note: The "document/literal wrapped" style removes this limitation; read on for more details.)

Another point to note about the document style is that there are no rules for how the SOAP body must be formatted. This can either be seen as a downside or a strength, depending on your perspective. It's a strength if you are looking for the freedom to handle the message the way you want, but a downside if you don't want to have to do the extra marshalling/unmarshalling work that it requires.

Encoded vs literal encodings

In addition to the RPC and document styles, there are two types of encodings: "encoded" and "literal".

Literal means that the SOAP body follows an XML schema, which is included in the web service's WSDL document. As long as the client has access to the WSDL, it knows exactly how each message is formatted.

Encoded, on the other hand, means that the SOAP body does not follow a schema, but still follows a specific format which the client is expected to already know. It is not endorsed by the WS-I standard because there can be slight differences in the way in which various programming languages and web service frameworks interpret these formatting rules, leading to incompatabilities.

This makes for 4 different style/encoding combinations:

RPC/encoded - RPC-style message that formats its body according to the rules defined in the SOAP standard (which are not always exact and can lead to incompatabilities).
RPC/literal - RPC-style message that formats its body according to a schema that reflects the rules defined in the SOAP standard. This schema is included in the WSDL.
document/encoded - Document-style message that does not include a schema (nobody uses this in practice).
document/literal - Document-style message that formats its body according to a schema. This schema is included in the WSDL.

There's also a 5th type. It isn't an official standard but it is used a lot in practice. It came into being to compensate for document/literal's main shortcoming of not having a standard way of specifying the web method name:

document/literal wrapped - The same as document/literal, but wraps the contents of the body in an element with the same name as the web service method (just like RPC-style messages). This is what web services implemented in Java use by default.

Is my understanding of all this accurate? Which approach do you think is the best? Let me know in the comments.



Anonymous said...

Wow Mike. Great detail there.
I was asked this question in an interview about 4 years ago. Ever since, once in a while, I search the web, but never got a satisfactory answer...till now. Great work.

-Raghu M

misha said...

Thank you, that is a great clear answer

Anonymous said...

Mike, You are awesome..
I liked the way you presented. it is crystal clear.. I was going thru lots of tutorials and spent lots of time to understand RPC/Document and other styles.. but could not succeed .. after reading your explanation i felt really comfortable in the concpets...Thanks a lot.. keep up this type of work..

Anonymous said...

Very nice and clear article. Thanks!!

Michael Angstadt said...

You're welcome everyone. Even after doing research for this blog post, I still wasn't 100% sure about everything, so let me know if you find any mistakes.

Anonymous said...

Great Work. I faced the same question in the interview and doesn't know the answer. Then I started searching in the internet for that and got your post. Its really useful I appreciate your attitude

Anonymous said...

realy liked your way of explaining..
it was worth reading this.

Anonymous said...

The best explanation I've found... Thank you!

Anonymous said...

Good One

Michael Angstadt said...

Thanks for all the compliments guys!!

Khadolkachan said...

Thanks a lot mike. :)

Anonymous said...

Googled for three hours to get a simple answer - Doc vs RPC. Finally got this, thanks.

Michael Angstadt said...

Glad I could help. :)

Anonymous said...

explained clearly awesome

UnboundSpirit said...

Thanks you Mike..Good article..upto the point and precise..

Dave E said...

Mike, thanks for this post. It's something I've looked into no less than a couple dozen times as I've tried to wrap my head around it.

There is one part of SOAP WSDL bindings called the SOAPAction property which is part of the 'operation' element. Given a good SOAP client this results in an HTTP header being sent to the server along with the XML content indicating the 'intent' of the request.

So, the SOAPAction header is very useful for document type requests as the action indicates the 'intent' of the request i.e. which service the request is intended for. Therefore, your server code really can 'marshall' the request. And, I might say, this header *could* be required for doc/literal services. And then depending on your Server implementation, some of this might be handled for you (JAVA/.NET), and some might not (PHP).

Obviously, for doc/wrapped or rpc/literal/encoded, the SOAPAction HTTP header would be redundant.

You might consider adding what part the SOAPAction plays in a doc/literal request as my ending question still was after reading your article - "how do you know which service is being requested with a doc/literal request?" I now believe the answer is the SOAPAction header.


Michael Angstadt said...


Thanks for the comment. Ugh, why must SOAP become tightly coupled with HTTP >:( . I will have to read up on the SOAPAction HTTP header and include it in my post.

68Bomber said...

Hi there... Thank you for the post. I am curious if anyone has played with converting an RPC encoded WSDL to a Document/Literal and then tried to communicate with an existing Web service.

They web service is publishing an RPC encoded WSDL. I am worried that the wire message wont be able to be interepreted. But the tool on the client side and the current versions of AXIS do not support RPC encoding.


Java Experience said...

I have seen developers which prefer Document style web service just because they read somewhere that Document style provides more features. But in reality, they should be comparing RPC and Document style web services before choosing one of them.

Sidhartha Ray said...

Thanx Mike !

Anonymous said...

Great work Mike! Really helped me out. Clear and simple. Thanks a bunch!

MC said...

Good one..

Anonymous said...

A little more details here and a very good example.

shravan raju said...

Very nice and precise one.

thanks a lot.

R said...

Thanks Mike!


Anonymous said...

Thanks for this article, Mike! I wish it hadn't taken years for something this clear to be written.

Anonymous said...

Excellent explanation.. I had been browsing thru the web for a clear explanation and this is by far the most candid one..

Anonymous said...

Very well explained. Great work.

Anonymous said...

Thanks for the info.....I need to clarify one thing i.e, if the request is RPC style is it mandatory that the response will have just one return element containing the response?

Michael Angstadt said...

"if the request is RPC style is it mandatory that the response will have just one return element containing the response?"

I believe so, yes.

vishwa said...

Checked in 2 different books and one slideshare presentation for the same in last two days and finally understood it fully here.
Thanks a lot

Anonymous said...

Thank you Mike. I've read three books on web services and none of them gave the clear explanation as you did in this post.

Anonymous said...

Great way to go the extra mile after an interview question. I remember an interviewer asked me a question about using Base 64 encoding as I had mentioned sending images this way. My answer wasn't very good, and I made a point of delving into it later. I've seen long writeups on the subject of SOAP bindings before that left one as unsure about the difference as they were prior to reading the writeup. You've put it concisely and clearly.

Vivek said...

Mike, Thank you for the valuable information. I have a question here though. In document style, how do we know which webservice method we are calling?

Anonymous said...

Good explanation . Best found till date about this concept.

Anks said...

Thanks a ton

Prem said...

Good Explanation

siva ram said...

That's Great explanation mike. Finally got answers to my questions :)

deepak chandra Joshi said...

WOW thanks a lot. This has given the clarity an good understanding. thanks again.

Binh Thanh Nguyen said...

Thanks, nice explanation.

Anonymous said...

Hi Mike. The part you have mentioned the similarity between a function and RPC just melted all confusion in my head about what an RPC is. I must have searched 20 websites but this part was not mentioned anywhere. Thanks a ton.