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

Question

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.

View more solutions

Comments

[U62]

"Do you prefer SOAP type services or REST/RPC style ones" should be "Do you prefer SOAP/RPC type services or REST style ones". SOAP is an example of the RPC concept applied to XML-over-HTTP. REST is altogether more subtle a concept.

[black sensei]

Really don't see what is not constructive in this post. As matter of facts, it's very useful to me today.This should not have been closed

[JB.]

Could you make that an actual link, please?

[Admin]

I would like to assume amazon is profitable not because of its API but because of the rest of their services. Just because a big corperation has used a paticular method of coding does not make it the best or even mean that they did their homework. For all we know it was a random choice.

[dfasdljkhfaskldjhfasklhf]

I'm looking at it from the opposite direction. They picked the best tool/methodology for the job based on the fact that they have to sell a product/service with it. They've gone through iterations, they've supported customers. They see flaws that an idea out of a book hasnt gotten to yet.

[SerialSeb]

HTTP has "standards" for authentication (Authenticate header) and errors (5XX responses). Packaging authentication in the payload is usually a bad idea, it breaks intermediaries that may cache them or process them, and it prevents the authentication scheme from being resued across sites. When you breach serendipity, you also breach REST.

[Asela Liyanage]

REST needn't be HTTP, it's protocol-independent.

[Asela Liyanage]

Amazon's API is not actually REST, it's just RPC.

[Richard Levasseur]

Another thing that ties into this is ease: Its 1) easy for people to understand an RPC approach instead of a rest approach and 2) Easier to implement ("here's a function and its arguments and return value")

[Admin]

In a few days it it going to be 2014. Google does not exhibit SOAP search API any more ... developers.google.com/soap-search That decision was actually made 3 years before the post above.