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?
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.