Best REST API documentation

Question

What is the best REST API documentation that you've come across?

What did you really like about it? HOWTOs? Videos? Code snippets? Browser based API explorer?

For example, I quite like the Flikr API documentation - http://www.flickr.com/services/api/flickr.photos.search.html, especially the API explorer.

The SOAPI-Explorer is also pretty cool - http://soapi.info/Code/JS/Stable/soapi-explore-beta.htm, although it lacks an overview of how to use things together.

What information is always missing from REST API documentation that catches you out? Eg, Date Formats.

Thanks!

Answer 1

The Gowalla API Explorer is one of the best I've seen. From a REST perspective, the Sun Cloud API is very good.

The key thing to remember when documenting REST systems is that you should be documenting the representations that are transfered across the wire, not the endpoints(Urls) that you have created.

Answer 2

I like Google APIs, but not all are RESTful. Next favorite is Amazon AWS API, e.g. S3.

Update

• Amazon AWS S3 REST API
• Google Buzz REST API