There was a link to an article posted yesterday or the day before on HN that attempted to interpret the original article. Here's the link: http://www.25hoursad

There was a link to an article posted yesterday or the day before on HN that attempted to interpret the original article. Here's the link: http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignInventMediaTypesNotProtocolsAndUnderstandTheImportanceOfHyperlinks.aspx http://www.25hoursaday.com/weblog/2008/10/24/RESTAPIDesignIn... I have to admit it's still a bit confusing to me. However, look at this snippet extracted from a comment by the author of the article you provided: "A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure). Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources)." And this snippet from the second: "The latest drafts of the OpenSocial specification have a great example of how a service can use existing technologies such as URI templates to make even complicated URL structures to be flexible and discoverable without having to force every client and service to hardcode a specific URL structure." This, to me, states that a restful api should implement api discoverability and give people a method to generate URI for any api call without hard-coding URIs into your code. A snippet from the article I linked-to that defines a URI template: <os:URI-Template>http://api.example.org/groups/ http://api.example.org/groups/{guid}</os:URI-Template> It's easy to imagine an api client transforming that template into a URI to retrieve group information without knowing about or caring about the specifics of the URI format -- it's a black box with the exception of '{guid}.' When provided with that information, a client can look at that template, substitute {guid} with an actual guid value, execute the URI, and get the desired results. This enables, amongst other things, the API to evolve without breaking the clients. The api clients must know how to interpret the set of template variable names used by the api ( guid, appid, selector, etc. in the example provided in the article), but that's it. I'm sure there's more to it than that, but that's the part that resonated with me.