Leave the REST to SOAP
Does being a SOAP advocate make me a REST detractor? I don't think it does. I like REST. There are a lot of advantages to it. It's based on proven, solid principles and technologies and it encourages good design by enforcing clarity and simplicity. I'd even go so far as to say that REST should be the first choice when deciding the technology for your web API. But the more complex your service model becomes, the easier it is for REST to backfire and the more likely it is that SOAP is a better choice.
There are two things that bother me about die-hard REST fanaticism. The first is the (often implicit) allegation that REST will solve your complexity problem and SOAP will make it worse. Whether you use SOAP or REST, you must start with a clean service model in order to end with a clean service model.
The second thing that bothers me about REST fanaticism is the assumption that REST is right for all service models. Oh... except the "wrong" ones. So if my service model doesn't fit into a RESTful paradigm, some restafarians would tell me the problem lies with my service model. Now, I can respect the architectural principles of REST and try to apply them in my design, but let me be the expert on my own problem space. Don't try to tell me what my service model should be.
I'm going to suggest some possible disadvantages to REST in an attempt to better understand when REST might not be a good choice:
The first disadvantage is that REST doesn't fit all service models. Sure, it fits a lot of them. You might even be able to convince me that it fits most of them. But what about stateful service models? What about service models that support a rich, complex data model? What about multi-step or transactional service models? I admit that REST could be stretched to support any one of these, but I think it starts to break down. And I don't think REST should be used to support two or more of these.
I often hear cited Amazon's statistic that 85% of its web API usage is of the REST interface. I'm neither surprised nor impressed. I'd guess that 85% of the API usage is limited to search/read operations and that most of the create and update operations are done with its SOAP API. And Amazon is not the only company that is generally a read operation. Google, Yahoo, Flickr, all of these have wisely chosen REST because their service models are limited generally to simple and atomic operations.
The second disadvantage is that REST doesn't explicitly define the service model it exposes. REST limits the vocabulary for describing your service model to XML and four verbs (create, read, update, delete). Many service models fit nicely into this vocabulary, and others can be compressed to fit. But a service model can only be compressed a limited amount before it experiences data loss.
When a service model is published using REST, the consumers of the API have to do a certain amount of interpretation to use it. This leaves room for ambiguity and bad assumptions. Using HTTP and XML lowers the entry barrier, but each developer might have to make their own assumptions on things like the subtle differences between "PUT" and "POST" and how to interpret and empty XML element. Some service models are simple enough that differences in interpretation are insignificant, but more complex service models will have to put much more effort into communicating to developers the subtleties of their API.
3. Finally, REST has no widely-adopted specifications (like WSDL) to use for defining the API. Programmers have to swallow raw XML because of the lack of tools and IDEs that rely on formal specifications. Documentation for a RESTful API is limited to human-readable text. Once again, the simple, atomic service models can more easily live with these limitations than can the more complex stateful models.
So don't be discouraged if your service model doesn't fit very well onto a RESTful paradigm. You're not alone, and it doesn't necessarily mean there's anything wrong with your design. Do what you can, and leave the REST to SOAP.
There are two things that bother me about die-hard REST fanaticism. The first is the (often implicit) allegation that REST will solve your complexity problem and SOAP will make it worse. Whether you use SOAP or REST, you must start with a clean service model in order to end with a clean service model.
The second thing that bothers me about REST fanaticism is the assumption that REST is right for all service models. Oh... except the "wrong" ones. So if my service model doesn't fit into a RESTful paradigm, some restafarians would tell me the problem lies with my service model. Now, I can respect the architectural principles of REST and try to apply them in my design, but let me be the expert on my own problem space. Don't try to tell me what my service model should be.
I'm going to suggest some possible disadvantages to REST in an attempt to better understand when REST might not be a good choice:
The first disadvantage is that REST doesn't fit all service models. Sure, it fits a lot of them. You might even be able to convince me that it fits most of them. But what about stateful service models? What about service models that support a rich, complex data model? What about multi-step or transactional service models? I admit that REST could be stretched to support any one of these, but I think it starts to break down. And I don't think REST should be used to support two or more of these.
I often hear cited Amazon's statistic that 85% of its web API usage is of the REST interface. I'm neither surprised nor impressed. I'd guess that 85% of the API usage is limited to search/read operations and that most of the create and update operations are done with its SOAP API. And Amazon is not the only company that is generally a read operation. Google, Yahoo, Flickr, all of these have wisely chosen REST because their service models are limited generally to simple and atomic operations.
The second disadvantage is that REST doesn't explicitly define the service model it exposes. REST limits the vocabulary for describing your service model to XML and four verbs (create, read, update, delete). Many service models fit nicely into this vocabulary, and others can be compressed to fit. But a service model can only be compressed a limited amount before it experiences data loss.
When a service model is published using REST, the consumers of the API have to do a certain amount of interpretation to use it. This leaves room for ambiguity and bad assumptions. Using HTTP and XML lowers the entry barrier, but each developer might have to make their own assumptions on things like the subtle differences between "PUT" and "POST" and how to interpret and empty XML element. Some service models are simple enough that differences in interpretation are insignificant, but more complex service models will have to put much more effort into communicating to developers the subtleties of their API.
3. Finally, REST has no widely-adopted specifications (like WSDL) to use for defining the API. Programmers have to swallow raw XML because of the lack of tools and IDEs that rely on formal specifications. Documentation for a RESTful API is limited to human-readable text. Once again, the simple, atomic service models can more easily live with these limitations than can the more complex stateful models.
So don't be discouraged if your service model doesn't fit very well onto a RESTful paradigm. You're not alone, and it doesn't necessarily mean there's anything wrong with your design. Do what you can, and leave the REST to SOAP.
Labels: interop, REST, SOAP, web services
posted by Ryan at 3:42 PM
6 Comments:
REST doesnt mean you have to use XML
"Finally, REST has no widely-adopted specifications (like WSDL) to use for defining the API"
What more do you need than RFC 2616? It defines the "API", i.e. GET, PUT, POST, etc..
This comment has been removed by the author.
Thanks for this articulation of what I've kind of been feeling about this stuff - specifically - like the comment about how compressing problem domains can become lossy - very good analogy.
My guess - Restafarians will begin to notice the breakdown of the rest model as they actually begin to use it for (useful) things - similar to the experience that is beginning in that other arena of technozeal, RoR......
thanks again. . .
You've made several incorrect assumptions that led you to your conclusion. After correcting these assumptions, you may or may not come to the same conclusion.
"What about service models that support a rich, complex data model?"
I'm not sure how this is a criticism of REST since REST does not dictate the data model. You made the assumption elsewhere in your document that REST resources are XML. This is incorrect and maybe why you think complex data models aren't possible.
"What about multi-step or transactional service models?"
See: http://www.xml.com/lpt/a/1459 - scroll down to "Transaction Lifecycle"
"REST limits the vocabulary for describing your service model to XML and four verbs (create, read, update, delete)."
Two wrong assumptions here. Again, REST does not say anything about whether your resources are XML, HTML, JSON, PDFs, whatever, it doesn't care. You should read:
http://tomayko.com/writings/rest-to-my-wife
Create, read, update, and delete DO NOT have a one-to-one correlation with PUT, GET, POST, and DELETE - this is a common misconception. See:
http://www.artima.com/lejava/articles/why_put_and_delete.html
The big take-away is that POST <> UPDATE.
There isn't much that doesn't fall into a RESTful paradigm if you _really_ look at what REST is and is not.
I totally agree with you. I also read your comments and Bradley's. I do agree with Bradley that you seems to be aggressive of the topic about (
Create, read, update, and delete; Complex data;XML).
Here is my thought on REST vs SOAP. The reason why we use REST or SOAP is to provide a SOA services to client developer. If the services (like you said) are simple services , like to get (Stock, weather, etc..) rest is the way to go. However, for most case, if we try to create complex services, REST can be painful.
The painful part is not how you developed it. Is how to make it easy for our client developer to use.
For sure, you can make all REST call "read,update,delete,create) using POST. However, client developer will not know about it. Service provider need to "clearly" documented each API (PUT,POST,GET...)(XML or JSON or HTML) (Exception) (Auth token, MD5, etc..). You will end up mixing many specification for a simple task (ex. Oauth with XML + JSON + MD5 hashing + POST/PUT + XSD + Error format). If I am a client developer, I will hate to read all those documentation. That's why sites like YAHOO/Facebook/Bebo/Flicker/Myspace/Photobucket/Google Provide an extra layer for developer to use like PHP/Java Script and handle those differcult REST call for you.
Why not just use SOAP over SSL SOAP standard auth with WSDL? I am not saying you can save time in documentation, but most of the case, client developer can POP SOAP UI out with the WSDL address and make api call right away. Care less about the data input format, error handling, auth method, hashing API name, etc...
I dare enough to challenge you for a speed test as a client developer. Pick a complex services (not those "Get weather" rest api). I open tools like SOAP UI, you can use google open REST tools, and see who can make a success call to the services quicker.
REST = (Open documentation > Find input/output format > "maybe" create xsd/xml object > find out if you need to (PUT/POST/GET...) > Service call.
SOAP = (compile wsdl > type the service name and all api will pop up. > Select an api and all required field will be enforced in code level > Service call.
And again, I am talking about complex services, which you have to have something like XSD/XML JSON to enforce the data structure.
I tried many REST services out there, and they are painful. The error doesn't make sense, is hard to even make a call! (PUT or POST or GET? What is the data attribute(String? Number?) Why I need to HASH MD5 in my call and put it to some predefine http header? Why they give me a GET method and assume I will send data that is small? Why they change input API (like the input xml) and I am not aware of it (like code error) until production? Why can't they doc. better? Why they put method call in one doc. input object in xml doc, error is some other place >.< I rather have one WSDL.
Not every one is super good developer or services provider. That's why we need a way to enforce the error object, input/output data structure, version, etc.. The most important thing is, your client user may be a high school student. Don't expect them to know (Get/put/post/xml/xsd/json/html/many RFC/).
Post a Comment
<< Home