title: Examples of the best SOAP/REST/RPC web APIs? And why do you like them? And what's wrong with them?
body: <p>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.</p>
  
  <p>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.</p>
  
  <p>Some points I'd like to cover:</p>
  
  <ol>
  <li><p>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.</p></li>
  <li><p>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?</p></li>
  <li><p>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?</p></li>
  <li><p>How should versioning be handled? Is it a good idea to have a <code>/v1/</code> 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).</p></li>
  </ol>
  
  <p>Also, any other opinions and points to cover would be useful.</p>
  
  <p>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.</p>
  
  <hr>
  
  <p><em>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.</em> </p>