WADL Just A Hypermedia Format?
[H]ere is my defence of WADL, called “It’s Just a Hypermedia Format”. Sometimes people say they’d like to do strange things with WADL, things I don’t approve of and things they wouldn’t think of doing with HTML. But WADL is just a hypermedia format. I like WADL because it’s a better hypermedia format than HTML or plain XML.
Excellent stuff; having someone like Leonard write about REST is a great addition to the REST community, IMO. I have one disagreement:
I’d like to try a system where sending OPTIONS to a URI gets you a hypermedia description of that resource, and see where that goes.
Why not use GET?
“Why not use GET?” you say. What would that GET request look like? Would it contain some pixie dust in the Accept header, or perhaps in the URI? How will the server know from the GET request that the client wants the hypermedia description?
I was indeed thinking of an Accept header; what is returned could either be the hypermedia description (which allows it to be specific for this particular resource), or link to a generic one, or be merged with the representation of the content.
GET is certainly a possibility. I like entertaining the OPTIONS possibility because it separates the state of the resource (GET) from the way you manipulate that state (OPTIONS). Of course that might be a false distinction.
There’s a big difference between asking for an object, and asking for a description of an object. But I agree with Leonard that OPTIONS is not really viable; no one uses it. GET is the right approach, but I think you’re getting two different things; two URLs in play. One for the object itself, another for it’s description (schema). Of course, many resources may be described by a single description.
Remember also the trick in Axis where appending ?help to a WS endpoint would give you some meta-data-driven ‘help’.
Patrick, that’s exactly what I meant with the comment above:
In some cases there will be a single description which covers multiple resources, in other cases, it may differ.
Butbut, I thought the idea behind REST was to let each verb do one thing, and do it well! So I’d use a separate verb for getting at the metadata: multiplexing on “Accept:”, although completely workable, seems like a hack.
On the other hand, how can I use a browser to see the description? the “?help” trick is nice. Multiplexing on “Accept:” is like OPTIONS in this regard.
I think the real question is not OPTIONS vs. GET, but the ease of retrieving the metadata.
Dispatching on Accept: makes sense if the what you retrieve is another representation of the resource. Whether this is the case or not is a design decision; but given that the meta-data may be resource-specific, I don’t see a problem at all.
I had some difficulty grokking “another representation of the resource”, but I think I get it now.
My working model is Atom, where you have one of several kinds of services based on the methods you support (list members gets you syndication, list, retrieve and delete members gets you a work queue, etc; see Joe Gregorio’s recent Do we need WADL? post for more).
So I thought it was a good idea for me to “divine” what kind of service I got pointed at based on “OPTIONS /atomEndpoint”. It’s not. A better idea would be to use some kind of microformat in the body of “GET /atomEndpoint” that tells me the methods I have available.
Or, as I think you’ve said, I could just “Accept: application/atom+meta-description” and parse that format to know what methods I have available and how to invoke them.
What do you think?
Yes, I think the microformat approach could be very reasonable here, and yes, that’s what I meant by sending another Accept header.