Ryan Heaton's Blog

Why ROI vs. SOI (read "REST vs. SOAP") Still Matters

The honeymoon with RESTful Web services is over. Now that we've had some time to get over the infatuation, let's take a fresh look at the principles of sound Web service API design. Despite how rocky our relationship with SOAP has been, it's time to confront our prejudices and accept both technologies for their virtues and vices.

In fact, I propose we give this discussion a new identity in order to help us put the painful memories, bitter tears, and long, sleepless nights behind us. Because it's not really about REST vs. SOAP anymore, is it? A well-designed Web service API is so much more important than the technology we use to implement it. So after we get past the name-calling and mud slinging, what we're left with is a set of fundamental architectural principles for Web service API design.

On the REST side of the playing field we have engineers who have a set of well-defined resources that they want to make available by defining a constrained set of basic operations that can be applied. On the other side, we have engineers whose operations are much more complex, maybe contextual, and perhaps interdependent. These engineers may or may not have a well-defined set of resources to which these operations apply. Rather than making a set of resources available, these engineers have a set of services they want to make available.

So on one end of the spectrum we have the need to design a Resource-Oriented Interface (ROI). On the other end, we have the need to design a Service-Oriented Interface (SOI).

Determining what kind of an API is to be published should be the first step in designing a good Web service API. And, trust me, it's not always easy to determine where your API fits. You may, for example, have a well-defined set of Gismo objects to which you can limit your operations to be create, read, update, and delete. But what if you want to provide a search operation for Gismos? In this case, the boundaries of the resource and the operation are less clear.

In any case, you will be able to make a much better choice of a development technology if you can first define whether your API is more Resource-Oriented or Service-Oriented. (By the way, it'll probably fit somewhere in between.) Choosing the development technology first is letting the tail wag the dog.

Still unconvinced? May I suggest that you subscribe to one or more of the common misconceptions about the current state of Web service development? Let's debunk those right now, shall we?

1. It is not easier to design a good Resource-Oriented Interface (think "REST") than it is to design a good Service-Oriented Interface. Actually, I'd suggest that for most engineers, an SOI is more intuitive than a ROI.
2. It is not easier to implement an ROI than it is to implement an SOI. In fact, the tools these days are much more mature for SOI. I've found that ROI developers often have to work directly with low-level protocol APIs, although that's changing fast.
3. It is not easier to consume an ROI than it is to consume an SOI. Which type of interface is easier to consume always depends on the platform of the consumers. Are they using a high-level, compiled programming language or are they in looser, more interpreted environment?
4. An SOI is not any less interoperable than an ROI. I'm going to assert that we've pretty much solved the issue of interoperability. I'm sure there are many of you who might disagree. Bring it on.
5. SOAP is not the only technology for implementing an SOI. Really. Just because you have a more service-oriented API doesn't mean you have to use SOAP. (Really? Whew!)
6. ROI is not always the best choice for supporting RIAs. Many AJAX frameworks (e.g. GWT) have their own RPC mechanisms that are much more SOI than they are ROI. Another example for Flash is AMF.

So what do you think? I say let's adopt a rational, reasonable approach to Web service API design and stop letting the tail wag the dog.

Comments

• Excellent post Ryan. I agree with all of your points save one -- it is clearly easier to take a REST than it is to wash with SOAP. After all, we IT types tend to wash as infrequently as possible. While at the same time we enjoy sleeping in. The unfortunate naming of SOAP has clearly been the real disruptive factor in this debate. And just for the record, I'm an SOI kind of guy.

  Posted by: prime21 on October 10, 2007 at 09:40 AM

• You know, I wouldn't really disagree with you, but I won't agree with you either. The point is, you'd have a hard time proving that it's easier to REST. What with all the SOAP client-side code generators (that are pretty good these days, I might add), it's really just a matter of generating your code and invoking it. To say that that process is harder that invoking a REST endpoint would be tough to uphold (especially in MY court of law).

  Posted by: stoicflame on October 11, 2007 at 09:35 AM

This work is licensed under a Creative Commons License.