URLs to the fore
By sandoz on Nov 05, 2007
David is right, put the URLs to the fore of any documentation of a RESTful API. The first thing i did when looking at the OpenSocial Data API documents was scan them to see what the URL patterns were. David provides a useful summary.
In general i recommend creating tables with URI templates, methods supported, content types produced/consumed and response codes returned. For extra bonus-points provide XPath expressions for XML representations that highlight the connected relationship to other resources. This really helps developers implementing the API and consumers. Or, use WADL with a style sheet as show by Mark Nottingham for the Yahoo news search.