REST's 'resource communication mechanisms' and 'on-the-fly' improvement of a client's knowledge of them.

Question

I'm trying to come to terms with REST, as defined by Roy Fielding. Recently I've been trying to wrap my mind around:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

The concept I'm interested in is in this quote:

The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand).

Specifically, what is knowledge of "resource communication mechanisms", how is that knowledge described in documentation/specs and realised in an implemntation? Then, how best to improve that knowledge 'on-the-fly'? I think I understand addressing 'the client's knowledge of media types'.

I have some guesses (PUT,GET, etc.) but would appreciate any suggestions, examples or pointers to RESTful API's that explicitly adress the issues in that quote. If it helps I'm thinking about these issues in the context of HTTP+JSON, I appreciate REST isn't limited to HTTP+*.

The Sun Cloud API has previously been cited as good RESTful design, I couldn't see where or how it addressed these specific issues - maybe a case of not seeing the wood for the trees?

Clarification:

What puzzles me is if PUT,GET,etc. are these mechanisms, this suggests a client knows which to apply to specific hyperlinks within some <media-type>, and this seems fragile, and might suggest hypertext-links map (directly) to resources.

Answer 1

Resource Communication Mechanisms

By "resource communication mechanisms", I believe Roy is referring to HTTP requests and HTTP verbs. He is just saying it without being specify to HTTP because REST is not dependent on HTTP. I would say that for 99.99% of all REST services, the resource communication mechanism is documented in RFC2616.

The Sun Cloud API meets these requirements because all a client needs to understand to use the API is how to do HTTP requests and the semantics of the returned media types. For example if a client does not understand what is contained in a document of type application/vnd.com.sun.cloud.Cloud+json then it will not be able to use the API.

This is in contrast with services like OData and SData that do not define new media-types, but assume a client knows how to extract domain data out of an Atom feed and expects the client to construct URLs based on a set of rules that define the URI space. This is in direct violation of Roy's recommendations.

Improved on the fly

To be honest, I can only guess at what Roy is alluding to here. I could imagine a scenario where downloaded javascript could be used to construct an url based on user input. This could prevent the server from having to explicitly generate an url for each element in a list.

Also, certain valid transitions could be enabled or disabled on the fly based on user input. Consider the case where you do not want to enable a submit button until the user has entered all the required fields. The retrieved document contains the link to allow the transition, but the downloaded code controls when and if the user can select the link.

Downloaded code could also, be used to dynamically change the verb on a link. If you wish to edit a resource, it could do a GET, if you want to delete that resource, you do a DELETE. This would allow the representation to only contain a single link but be able to perform multiple operations.