[rest-practices] text/html representation?

[Mark McLoughlin]

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?

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

Cheers,
Mark.

On Wed, 2010-04-28 at 08:14 -0400, Bill Burke wrote:
> A weird idea has been going through my head lately.  What if, for when 
> its practical, have your edit/action links accept 
> application/x-www-form-urlencoded, and the rel attribute of the link 
> points to an html form describing the interaction.
> 
> Mark McLoughlin wrote:
> > Hey,
> > 
> > I was trying to think of some simple advice for people designing REST
> > APIs - things like "if you're documenting the URI scheme, it's not
> > HATEOAS"
> > 
> > Would it be a worthwhile exercise for API designers to add a text/html
> > representation of their resources? with forms for action buttons etc.
> > 
> > That way you could be confident your really API is hypertext driven. It
> > would also be a nice way for API users to browse the API
> > 
> > Just a thought ...
> > 
> > Cheers,
> > Mark.
> > 
> > _______________________________________________
> > rest-practices mailing list
> > rest-practices at redhat.com
> > https://www.redhat.com/mailman/listinfo/rest-practices
>