[rest-practices] text/html representation?

[Bill Burke]

Mark McLoughlin wrote:
> Yeah, I was thinking along similar lines
> 
> With html, a form describes the parameters which can be POSTed
> 
> Does a RESTful API need something similar for parameters to an action
> link?
> 

IMO, its overkill.  Unless <vm> elements are going to be rendered, I 
don't see the point of embedding descriptive information other than a 
schema URL or link rel URL.  Let the rel attribute point to an html form:

<vm>
    <link title="reboot" rel="/rhelv/reboot.html" 
type="application/x-www-form-urlencoded"/>
    ...
</vm>

Or, if not the rel attribute, define a new attribute.

> We had been assuming any action parameters would be passed using an
> xml/json/etc. representation of the "action resource", but if we take
> the html form analogy, we could actually pass them using query
> parameters using application/x-www-form-urlencoded as you say
> 
> I'm thinking along the lines of:
> 
>   <vm>
>     ...
>     <actions>
>       <action rel="reboot" href="..."/>
>         <input name="async" type="bool"/>
>         <input name="foo" type="enum>
>           <option>FOO_BAR</option>
>           <option>FOO_BLAA</option>
>         </input>
>       </action>
>     </actions>
>   </vm>
> 
> After looking at it, though, I'm coming back full circle because:
> 
>   - HTML forms accept encodings other than urlencoded - likewise, 
>     there's no reason to restrict ourselves to urlencoded
> 
>   - The example form above starts to look like a schema - so, why not 
>     just have a real XML schema for the representation accepted by the
>     action link
> 
> With the text/html representation of a resource, though, it would make
> sense to represent action links with a <form> generated from the XML
> schema for the action representation
> 

IMO, this is what the media type is for.  I never really agreed with 
those that say "application/xml" is good enough.

-- 
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com