Steve Vinoski writes
One problem I noticed, though, was that the client developers asked for a “REST-like interface” and also for a document listing all resource URIs, and for each one, the HTTP verbs that apply to it, the representations available from it, and what status codes to expect from invoking operations on it. Those two requests are sort of mutually exclusive, depending on what “REST-like” means; for a proper RESTful system, you don’t need a document like that, at least not the type of document they’re asking for.
Normally, I tend to agree with Steve on most technical issues. Taken _literally_, his statement in the last sentence is technically correct - you don't need
such a document. A good Scout doesn't need
a waterproof container filled with wooden stick matches to light a fire - he can rub two sticks together. More importantly, though, I do not consider that the two requests his clients have made to be mutually exclusive. I have long held that such a description offers significant value.
While it is true that each resource in a RESTful system exposes a uniform interface (in the case of HTTP, the set of HTTP verbs, including GET, PUT, POST, DELETE, etc) it is not the case that each resource must enable
each verb in that interface. Hence, the 405 Method Not Allowed HTTP response. All perfectly RESTful.
It would be a real waste if a developer writing an agent for some resource(s) wrote a bunch of code to invoke, say the PUT verb, only to find when engaging that resource(s) that the response was consistently a 405 Method Not Allowed. Oops! Well, it was a learning experience writing that code - so not all is lost. Maybe, next time, he'll use Curl to invoke an OPTIONS request to determine which verbs are permitted, though it should be noted that the inclusion of an Allow header field is not guaranteed since RFC2616 says only that it SHOULD be included in a 200 response.
Then, there's the issue of the representations available for a given resource. Clearly, REST defines an architecture in which the client need not know the types of representation that might be returned for a given resource. This enables such agents as crawlers and spiders to be written that can scour the web looking for who knows what. This is "A Good Thing(tm)". Additionally, there can be agents such as browsers written that understand how to deal with many of the predominant types of representations - though in the case of a browser, the semantic that applies is (typically) limited to the rendering of the representation on a display.
However, if the resources that I am exposing are to be fully appreciated by the full range of agents that will interact with my resources, expecially when we're talking about XML representations of say a PurchaseOrder, or a Clinical Document from HL7, exposing a description that said: "resources that are identified by the following URI template are represented by the following representation types - and in the case of application/xml - by the following schema and support the following verbs". Such a description is valuable for purposes of tooling that simplifies the development by generating stub/skeleton code (for either the client or server), and is especially valuable if one wishes to distribute concurrent development of the overall system (client(s) and server(s)) by first describing the specifics of the (additional) interface constraints that the RESTful system will expose between these components.
There are two, possibly equally qualified, candidates for such a description, amongst a field of many more that have not yet achieved the same level of interest, - WSDL2.0 and WADL. Some colleagues of mine in IBM Japan Research have published a paper
that attempts an unbiased comparison of the two that you may find of interest.
Bottom line, for me, is that I have long believed that RESTful systems would benefit from addition of exposed metadata in the form of descriptions such as those proposed by WSDL2.0 and WADL. Certainly, from my perspective, REST and a description of the constraints on an application/system's interface are not mutually exclusive of one another.