Examples of the best SOAP/REST/RPC web APIs? And why do you like them? And what's wrong with them? [closed]

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:

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

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

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

4. 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 like have the version in the request payload or query? How long would you expect a version of an API that you'd built against to be supported for (i.e. if v2 was introducted, what would be your expectancy around the lifetime of v1).

Also, any other opinions and points to cover would be useful.

I'm deliberately staying vague on the actual type of API we're implementing, as I'm looking for general guidance in terms of what people think are good APIs and implementation mechanisms, so this post and its answers will be useful to more people in the future.

Note: I have searched and can't find a generic question about this - they all seem specific to a certain type of API - but if it is a duplicate then please let me know. Also if it should be community wiki (I think people ought to get credit for answers so I haven't made it one) then please let me know and I'll change it to be.

Solution 1:

Here's my take.

1. Although coming from a Java standpoint, I actually prefer REST. SOAP envelope with multiple namespaces and its complex structure is abomination. It tries to solve mostly imaginary problems, and doesn't solve anything efficiently. Only thing about SOAP I've found useful is that it has standards for authorization and errors. On the other hand, both could be solved much easier by including four standard attributes in root XML element - username, password, errorCode, errorDescription.

2. Good API description and documentation is indeed all that matters. Difference between REST and SOAP in mature framework is mostly in a few lines of configuration.

3. For SOAP, send hash as part of SOAP security; for REST, I like to package everything in payload and avoid HTTP headers for authentication. I have only subjective reasons though, since I had to battle with frameworks which don't easily expose HTTP headers.

4. My personal preference is having different URIs for different protocol versions. In my experience, this gives you more flexibility in newer versions, and old clients which connect to unsupported versions of a protocol stop working immediately and for obvious reasons. Also, sometimes you can map old version of application to old URI, to avoid having legacy support code in new server version.
   
   As for how long you support old version of protocol... ideally, as long as you have clients which use it. This is more business than technical decision. You should support at least one previous protocol version. It's usually in your interest to push clients towards new version to lower legacy support costs; from the clients side, new version should mean new features, better protocol, and some sort of additional business incentive (if new features alone are not enough).

Solution 2:

You might be interested in Joshua Bloch's presentation "How to Design a Good API and Why it Matters". Joshua Bloch is the author of "Effective Java" and a Principal Software Engineer and Chief Java Architect at Google.

Abstract: http://portal.acm.org/citation.cfm?id=1176622

Slides: http://lcsd05.cs.tamu.edu/slides/keynote.pdf

Video: http://www.youtube.com/watch?v=aAb7hSCtvGw

Solution 3:

Versioning for REST using Content-Type headers is covered well here: http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Solution 4:

I'd see what Amazon is doing - http://aws.amazon.com/ - the guys making money off this stuff obviouslly will have learned more lessons than anyone else.

Other API's I'd look at - salesforce.com and Microsofts CRM api was rather interesting. Twitter has a battle hardened REST api too.

Solution 5:

The RPC approach is also a good option. It reduces the overhead, and projects like Ice,Google Protocol Buffers and Apache Thrift are making it easier to develop RPC based services easier.

If you do not have to provide a web based API, then RPC can also be a choice you want to explore.