Choosing a method for a webservice

Question

I'm asked to set up a new webservice which should be easily usable in whatever language (php, .NET, Java, etc.) possible. Of course rolling my own can be done, accepting different content-types (xml / x-www-form-urlencoded (normal post) / json / etc.), but an existing method or mechanism would of course be prefered, cutting down time spent on development for the consumers of the service.

The webservice does accept modifications / sets (it is not only simply data retrieval), but those will most likely be quite a lot less then gets (we estimate about 2.5% sets, 97.5 gets). The term webservice here indicates the protocol should go over HTTP, not being able to implement it totally client sided (javascript in the end-users browser etc.), as it needs specific user authentication.

Both gets and sets are pretty light on the parameter count (usually 1 to 4). Methods like REST (which I'd prefer for only gets), XML-RPC & SOAP (might be a bit overkill, but has the advantage of explicitly defined methods and returns) are the usual suspects.

What in your opinion / experience is the most widely 'spoken' and most easily implementable protocol in different languages (seen from the consumers' viewpoint) which could fullfill this need?

Answer 1

A SOAP service has the advantage of being discoverable. In .NET (and, I assume, other languages), you simple create a new web service class (.ASMX in ASP.NET) and add whatever methods to the interface that you require. The framework will generate a WSDL for you that is retrievable via HTTP. That WSDL contains a class definition that is used by the calling application supply correct parameter names and types for each method. etc.

A REST or other typically non-discoverable service has the disadvantage that you'll have to maintain documentation for that interface manually. It can be more difficult to debug communication issues with clients without the information within and enforcement of a WSDL.

Answer 2

SOAP is a nightmare for almost any consumer except Java and/or .NET, and unless things have changed, getting a Java client to talk to a .NET server (or vice versa) is a pain. If you go the SOAP route, you pretty much consign yourself and the consumers of your web service to being beholden to tool support, because nobody wants to deal with SOAP by hand.

You can write a consumer for a RESTful web service in pretty much any language, because all it needs is an HTTP library, although there are libraries for most mainstream languages to help with things like content-type negotiation, etc. Those libraries are a big win for the server, too, btw.

A truly RESTful API is discoverable by definition: Hypertext As The Engine Of Application State (HATEOAS) is one of the defining characteristics of REST. To be fair, this is typically ignored in the real world, largely because it's overkill. Something like AtomPub or one of the cloud server management APIs from Sun is probably a good example of a truly RESTful service.

No matter which approach you take, you should be writing clear documentation on your own instead of relying on auto-generated docs. Those are useful references when needed, but they don't take the place of good, hand-written documentation.

Answer 3

We did a lot of research on this and ended up going with REST. A lot of well-thought-of web services use REST including Amazon S3. I think Gmail also uses REST on the back end.

From my observation, RESTful web service design seems to be becoming more prominent as the advantages of its design and disadvantages of other designs such as SOAP become more obvious through time and experience.

The reason that REST seems to work well is that it is a natural fit for the client-server nature of the web with its separation of safe and idempotent GET requests, idempotent PUT requests, and POST for requests that are neither safe nor idempotent. Its been around for a long time so a properly laid-out RESTful web service can be consumed by a variety of web clients, some that you might not even anticipate. An example of this is that a web crawler will know only to request resources using GET because it is guaranteed not to affect the resource whereas PUT and POST requests have different rules.

After we decided on a RESTful service architecture, I read this book: RESTful Web Services in order to learn the basics. If you decide to read it, know that the book is perhaps twice as long as it needs to be so you'll have to be judicious about what to read and what to skip - cause you'll want to skip the fluff.