At my company we're starting to branch into web APIs to access and update our data; initially for partners but then likely to the public in future. At the moment the way the API will look (e.g. SOAP, REST, RPC) is completely open and we haven't made any decisions yet, so I'm interested in both examples of web APIs people think are good, and why you think that.
What I'm interested in is opinions from people using different languages (we're likely to be offering the API to people using a number of platforms, particularly including .NET, Java, ActionScript and JavaScript) about web APIs that you think are good examples, and that you've had good experiences with.
Some points I'd like to cover:
Do you prefer SOAP type services or REST/RPC style ones? I suspect that people with platform support (e.g. .NET, Java) will prefer SOAP ones and people using languages without platform support will prefer the others, but I'd like to validate that assumption.
Do you care whether an API is actually RESTful or whether it is a plain old RPC style HTTP GET/POST? If so, why do you care? Is it more important that an API describes itself correctly (i.e. don't claim to be RESTful if it's RPC style) than whether it actually is one of the two?
We need to verify who is using the service. I've been looking at the Amazon S3 authentication which uses a public identifier and a private token that's used to hash the parameters of the request into a verification token (this is also similar to flickr). Have you used this type of authentication before, and how did you get on with it? Are there any hash algorithms you find problematic (i.e. not supported by your platform)? Would you prefer to send the hash in an HTTP header or in the URI?
How should versioning be handled? Is it a good idea to have a
/v1/type subdirectory so that future versions can be added alongside, or would you do something differently