Earthly Powers

URLs to the fore

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.

Posted at 01:26PM Nov 05, 2007 by Paul Sandoz in REST  |  Comments[0]