Web service architecture: simple REST vs complex SOAP
| Contributed by: | Gudmundur A Thorisson |
| Originally posted: | 19th July 2009: 4:24 pm |
| Last updated: | 25th November 2009: 12:59 pm |
| Short URL: | http://gen2phen.org/node/2647 |
 Web services and exchange formats |
 Public - anyone can view |
In recent years a battle-of-sorts has been raging in Web developer circles between proponents of two main web service architecture styles: Simple Object Access Protocol (SOAP) on one hand and REpresentional State Transfer (REST) on the other. I won't go into details about the characteristics of each, but what I do want to present in this post is rationale for choosing one of these styles rather than the other for implementing web service APIs in our domain of interest (G2P databases), as an extension to Glen's previous comments on implemention. I hope this will generate some discussion in the group and help to align our efforts on this front.
Why not SOAP?
For many developers new to web services, the fashionable thing to do for some time has been to whip up some SOAP services and be done with it. A prominent reason cited is that there's a lot of SOAP tools available (software libraries, IDEs, debuggers, testing frameworks), including support for auto-generating client libraries: just point a suitable IDE tool to a WSDL description which describes the API to create code 'stubs' which can be used when programming client applications. Also, because SOAP is all about passing objects around and calling methods on them, developing clients is by and large an extension of regular objected-oriented programming. But this convenience helps to gloss over a number of downsides to this approach. SOAP is in fact anything but simple and brings a high level of complexity to both client and server code, and a lot of the aforementioned tools exist chiefly to work around said complexity. Also, the SOAP approach tends to lead to a customized, non-standard interface which is only meaningful in the context of the particular application, resulting in client-code which is tightly coupled to the API.
Having said that, this level of integration, flexible security and other sophisticated features of the SOAP/WS-* stack makes it an appropriate choice in some settings, such as enterprise-level, corporate networks. But in the context of Web 2.0 style, loosely coupled service-oriented architecture (SOA), the SOAP approach presents a complexity barrier for client developers.
Why REST?
A one-sentence summary might go as follows: REST is simpler to understand and use, it is scalable, and it works the way the World Wide Web itself does when we navigate from page to page using a web browser. REST is a resource-centric approach (rather than the message-centric SOAP); clients navigate between web resources identified by URIs and invoke a set of standard actions or methods (as defined in the HTTP spec) on these resources (GET, PUT, POST, DELETE), further described here. In contrast to SOAP, there is no need for a big, complex description of the service interface itself, because standard HTTP itself is the interface. This vastly simplifies client development because using a RESTful API is almost the same as making requests for normal web page URIs. No complex libraries or programming techniques are needed.
Many major Web 2.0 Internet players today increasingly choose RESTful architecture over SOAP: Google Data, Google Maps are REST, as are Flickr, eBay, FriendFeed and many other widely used public APIs. Some services, such as Amazon S3, offer both SOAP and REST APIs. Generally, these API providers want as wide adoption as possible, which means keeping the API simple, which means avoiding the SOAP/WS-* bloated stack.
What about service description and code generation?
By now someone is surely thinking: "but dude, I really want my client code generator!!". A given RESTful API is normally simple enough that it can be described adequately on a human-readable page (see good example here), whereas a SOAP API cannot even feasibly be used without a WSDL. However, there are methods for describing RESTful services contract-first in a machine-readable way (via WSDL 2.0 or WADL, see more here). So, we could reap some of the code-generation benefits of the SOAP-approach here if those features are desired.
Conclusion
The take-home message from this post is basically the good, old KISS (Keep It Simple Stupid). Keeping your API as simple as possible makes life easier for people using it. Choosing a SOAP-based architecture for web services for G2P databases would introduce a lot of unnecessary complexity, where in most cases a simpler REST API would be a better strategy. But if you feel SOAP is necessary, consider offering a RESTful API as a simpler alternative if possible and appropriate.
(2 votes)
Tags:
Comments
Comments
#1 I agree that REST is good,
I agree that REST is good, but I do like SOAP/WSDL (when it works). I think sticking to document/literal encoding and creating services contract-first helps avoid some of the problems of SOAP... although the very fact that the former is an issue at all begins to suggest some of the difficulties you can blindly enter into.
I would generally be of the "provide both interfaces" school of thinking. Axis2, for instance, allows this to be done relatively easily. However, for our purposes we might want something lighweight, e.g. to bolt onto an existing LSDB system, so perhaps a REST interface on its own would be preferable.
I also think that REST with XML schema/s is good practice as this simplifies client development in some cases, and also allows validation and better compatibility across implementations.
In our case the main schema should come out of the model/interchange format work anyway. It would be good to be basically passing around instance documents of this schema where possible.
#2 I largely agree on the REST
I largely agree on the REST w/ XML schema point, Glen. But I would
also emphasize that in many scenarios existing formats or conventions
(e.g. Atom feed XML, or tab-delimited text) could potentially be be
used to good effect, rather then purely sticking with custom XML
based on a domain-specific schema(s). Or perhaps even a combination of
the two (got another post coming on that topic).
Regarding contract-first development; there's a nifty little tool which assists in creating a WADL machine-readable descriptions for a RESTful service starting from just a URL with some parameters, and even creates some client code stubs:
http://tomayac.de/rest-describe/latest/RestDescribe.html
#3 Just like to add link to GMOD
Just like to add link to GMOD meeting notes I just found.
http://gmod.org/wiki/January_2009_GMOD_Meeting#A_RESTful_Interface_for_M...
Would be good to try to sync specs with other efforts, at least on general level.
#4 Indeed, SOAP in anything but
Indeed, SOAP in anything but simple, but so is IP, TCP, HTTP and many other
protocols we use daily. The beauty of SOAP is that it abstracts this complexity
from both the server side developer as well as the client side developer. Once
a SOAP framework is set up, adding a new service takes no more time than adding
a normal (local) function. Doing a SOAP call from a client is ridiculously
simple (see attached code snippet).
Many people get frightened when they see a WSDL file. However, this file can
be generated by the server (from the webservice source code) and neither the
server side developer nor the client side developer will ever read it.
A big advantage of SOAP is that SOAP is able to serialise objects (as can be
seen in the code snippet too). Complex objects are the same on the client side
as well as the server side. This eliminates the need for parsing of the output,
and therefore supports interoperability, in contrast to a REST service.
Note that serialisation with REST is also possible, but only when the same
programming language is used at the end points (encoding dictionaries as a
string and evaluating them at the client side for example). In general, an
encoding scheme is needed to correctly interpret the output. Especially when
the output is a nested object, this is not feasible.
---
# Example SOAP call (in python).
# These first two lines are only needed once.
from SOAPpy import WSDL
o = WSDL.Proxy("http://path-to-a/service.wsdl")
# This is the real call.
m = o.transcriptInfo(build = "hg19", accNo = "NM_002001.2")
print m.CDS_stop
---
In conclusion, the SOAP infrastructure is able to handle complex structures
without increasing the complexity at either the server or client side. There
is no need for serialisation or deserialisation in the developed code, which
reduces the chances of errors and keeps the developed code clean and simple.
#5 Actually, serialization does
Actually, serialization does not need the same programming languages on both sides at all. Just the day before yesterday I was writing a short script (I need to keep my mind active while on holiday, eh) to keep track of the EUR/MXN exchange rates, after I found a currency converter website with an API. I saw they used REST in conjunction with JSON to send an object back to the user that could contain error messages as well as a proper result object. I had the thing setup in minutes. JSON has bindings in virtually all programming languages (also see the website for more info).
I was happy to see they were using REST because I could simply test the correct API call in my browser and the system console before writing any code. Granted, the website had to write a short page about how to use it instead of just giving me the link of the WSDL file such as is possible with SOAP interfaces, but I kind of appreaciate some basic usage examples anyway.
#6 Using JSON is indeed an
Using JSON is indeed an option, but it proves my point of the need of a seperate serialiser.
Have a nice vacation by the way. :)