The reason for this post is some bad experience I had recently with one (or in fact multiple) webservices, so excuse me if this sounds a bit like a rant.
First of all I’d like to say that I absolutely love webservices. They are one of the greatest things since the invention of sliced bread. They allow interaction between different parties using a standardized communication protocol (well mostly at least) and don’t require any special client software.
Basically there are three kinds of webservices:
Proprietary Webservices: The least “open” kind of webservices. While they usually use a standard protocol (HTTP), the usage is completely dependent on the service provider. A client needs to know the full API to communicate with such a service. They are often used by URLs such as this:
http://example.ws/myApplication/addUser.php?firstname=Michael&Lastname=Meier&favColor=blue
In other cases the whole interaction is defined in the payload and HTTP is only used for communication. I’d advise to avoid creating new proprietary webservices nowadays, but you can’t always avoid existing services.
RESTful Webservices: My personal preference for most tasks. The URLs usually represent objects on the service side and the default HTTP methods (GET=Read, PUT=Update, POST=Add/Insert, DELETE=Delete) are used to access those objects (similiar to CRUD in databases, but not exactly the same). Errors are indicated using the appropriate HTTP error code and a message in the body. They can use basic authentification provided by HTTP but further features like transactions usually need to be implemented in the payload. RESTful services don’t save any information on the client state which makes creating such services a lot easier. Calls typically look like this:
GET http://example.ws/myApplication/user/12345 to get the information for user 12345
PUT http://example.ws/myApplication/user/12345 to update its information (data in body)
WS-* (SOAP) Webservices: Often called “Big Webservices”, these offer the most functionality. There are a lot of WS-* extensions that add functionality to the web service protocol like Reliability, Security, Transactions and advanced Authentification. SOAP uses (xml-style) messages that can be transfered using a lot of different protocols (usually HTTP, but FTP, Email, even MMS would also be possible). SOAP services keep track of the client state to allow process chains. They are also described by a WSDL (WebService Description Language) file which contains information how to contact the webservice and which methods are available (including parameters), making it possible to use the service without much inside knowledge.
After reading this one might think that SOAP services are the go-to solution for all your webservice needs. Unfortunately that seems to be the conclusion many executives have come to as well. What they don’t realize is that SOAP generates a huge overhead and processing SOAP requests and responses takes a lot more work than handling the simpler RESTful operations. Getting catalog information from a RESTful service is as easy as calling the responsible service with the category as a parameter like “GET http://example.ws/catalog/programming”. This operation in SOAP would look like this:
POST http://example.ws/catalogSvc
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header />
<soap:Body>
<m:GetCatalogList xmlns:m="http://example.ws/catalog">
<m:Category>Programming</m:Category>
</m:GetCatalogList>
</soap:Body>
</soap:Envelope>
“Slightly” more complicated and that is without any soapHeader information.
So using SOAP services is bad? Not at all. They are great when they are needed. But it is important to know when they are needed and when they’re just bloat (and often slower). Let’s get back to my bad experience mentioned above. I’ll use the catalog example above. We needed a web service that would provide us with 1) a list of all categories (multiple tiers, so preferably a tree like structure), 2) the list of books for certain category and 3) detail information for each book. The service would only be accessed using PHP from a limited number of (known) users.
From this information you should come to the conclusion that a SOAP service would probably be a bit overkill but a single RESTful service with three interfaces (/catalog, /catalog/category/x, /book/x) would do perfectly fine especially since we only need read access. If for some reason you really, really, really want to use a SOAP service (a client may already exist which uses SOAP), a single service with three operations (e.g. GetCategoryList, GetBookList, GetBookDetails) would be the smart choice.
Well, I mentioned “the ugly” in the title (and I didn’t mean proprietary services). This is what we received as a web service in the catalog case: Not one, not two, but three separate SOAP services with different URLs for each of the operations. Just don’t do stuff like that. Seriously. Don’t. There is hardly ever a reason to spread information that belongs together over different services. It’s BAD DESIGN.
