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
