jonm · November 25, 2010 10:52
diff --git a/xhtml_api_example.html b/xhtml_api_example.html
 <!-- quick demo of XHTML API style -->
 <html>
 <body>
  <div class="dvr">
    <p>This div (and all it contains), represents a DVR set-top box. Some parts, like this text, may be
       ignored by programmatic clients. A client can recognize it by its @class attribute. The general
       convention here is one of inclusion rather than position, and clients make a lot of use of the
       "//" (descendent) XPath operator rather than the "/" (child) operator.</p>

    <!-- by the next form's @class I can recognize this is what I use to assign a friendly name.
         This @class would be called out in the documentation. -->
    <form class="dvr_name" method="POST" action="...">
      <!-- action URL completely under control of server -->

      <!-- overloaded POST: since HTML still doesn't let me have PUT or DELETE as the method for
           forms, this is the best we can do. This lets human clients still do everything
           from a browser. I'm still up in the air as to whether a programmatic client should
           submit an overloaded POST, or whether it should recognize this convention and turn it
           into a PUT. I'm leaning towards the former to promote loose coupling. -->
      <input type="hidden" name="_method" value="PUT"/>

      <!-- names of important inputs get documented so clients know what to supply. Clients may be
           able to read current values from form inputs too, like the current "Family Room" name for
           this DVR. Find me with xpath ".//form[@class='dvr_name']//input[@name='stb_name']" 
           starting from the enclosing DVR div -->
      <label>Change the name of this DVR:</label>
      <input type="text" name="stb_name" value="Family Room"/>

      <!-- hidden inputs and ones that are not understood are submitted as-is by the client, just like a 
           browser would -->
      <input type="hidden" name="convenient_state_for_server" value="some stuff"/>

      <!-- include a button for the non-programmatic clients -->
      <input type="submit" value="Rename"/>
    </form>

    <!-- Data values are identified by spans with certain classes, which allows for convenient
         embedding in human-friendly structure. This one is ".//span[@class='mac']". -->
    <p>This DVR's MAC address is <span class="mac">DEADBEEF1234</span>.</p>

    <!-- For subobjects or related objects, I like to specify an enclosed div with a self link as
         follows, to make it relatively easy to inline the remote resource here if needed; the
         client can always find this div and instantiate a domain object; there's a reusable proxy
         pattern here where you can then detect if you are a shallow link or an inlined concrete
         object. -->
    <div class="recordings">
      <p><a rel="self" href="...">List of recordings</a></p>
    </div>

    <!-- alternative to div-with-self-link -->
    <p><a rel="recordings" href="...">Other link to list of recordings</a></p>
  </div>
 </body>
 </html>
	<!-- quick demo of XHTML API style -->
	<html>
	<body>
	<div class="dvr">
	<p>This div (and all it contains), represents a DVR set-top box. Some parts, like this text, may be
	ignored by programmatic clients. A client can recognize it by its @class attribute. The general
	convention here is one of inclusion rather than position, and clients make a lot of use of the
	"//" (descendent) XPath operator rather than the "/" (child) operator.</p>

	<!-- by the next form's @class I can recognize this is what I use to assign a friendly name.
	This @class would be called out in the documentation. -->
	<form class="dvr_name" method="POST" action="...">
	<!-- action URL completely under control of server -->

	<!-- overloaded POST: since HTML still doesn't let me have PUT or DELETE as the method for
	forms, this is the best we can do. This lets human clients still do everything
	from a browser. I'm still up in the air as to whether a programmatic client should
	submit an overloaded POST, or whether it should recognize this convention and turn it
	into a PUT. I'm leaning towards the former to promote loose coupling. -->
	<input type="hidden" name="_method" value="PUT"/>

	<!-- names of important inputs get documented so clients know what to supply. Clients may be
	able to read current values from form inputs too, like the current "Family Room" name for
	this DVR. Find me with xpath ".//form[@class='dvr_name']//input[@name='stb_name']"
	starting from the enclosing DVR div -->
	<label>Change the name of this DVR:</label>
	<input type="text" name="stb_name" value="Family Room"/>

	<!-- hidden inputs and ones that are not understood are submitted as-is by the client, just like a
	browser would -->
	<input type="hidden" name="convenient_state_for_server" value="some stuff"/>

	<!-- include a button for the non-programmatic clients -->
	<input type="submit" value="Rename"/>
	</form>

	<!-- Data values are identified by spans with certain classes, which allows for convenient
	embedding in human-friendly structure. This one is ".//span[@class='mac']". -->
	<p>This DVR's MAC address is <span class="mac">DEADBEEF1234</span>.</p>

	<!-- For subobjects or related objects, I like to specify an enclosed div with a self link as
	follows, to make it relatively easy to inline the remote resource here if needed; the
	client can always find this div and instantiate a domain object; there's a reusable proxy
	pattern here where you can then detect if you are a shallow link or an inlined concrete
	object. -->
	<div class="recordings">
	<p><a rel="self" href="...">List of recordings</a></p>
	</div>

	<!-- alternative to div-with-self-link -->
	<p><a rel="recordings" href="...">Other link to list of recordings</a></p>
	</div>
	</body>
	</html>