If servers control their own namespace without a fixed resource hierarchy, how do clients, and more importantly client developers, get to learn or discover URIs of resources? In a new article, Subbu Allamaraju discusses how to describe a RESTful API, focusing on using hypermedia instead of an out-of-band description format such as WADL or WSDL 2.0.
Regarding the use of these formats, Subbu writes,
This approach, however, contradicts some of the fundamental principles of REST, as paraphrased by Roy Fielding above. Even if we ignore this objection, for those attempting to build distributed applications over HTTP RESTfully, the fundamental question remains. How can a server get away without formally defining a contract? Without a contract, how can we make sure that clients and servers are implemented correctly, not only to respective design specifications, but to other business/technical policies in place?
He goes on to show an example that aims to follow REST principles, but misses the hypermedia aspect and requires extensive documentation of its URI structures. He then shows an alternatives that embeds links to enable a client to discover many of these aspects at runtime.
Check out Subbu's article to learn about hypermedia in RESTful applications.