Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Sample document using XHTML for hypermedia APIs.
<!-- quick demo of XHTML API style -->
<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"/>
<!-- 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>
<!-- alternative to div-with-self-link -->
<p><a rel="recordings" href="...">Other link to list of recordings</a></p>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment