[microformats-discuss] Re: XHTML-REST -> APIs
Dr. Ernie Prabhakar
drernie at opendarwin.org
Thu Oct 13 08:54:33 PDT 2005
Hello again all,
Okay, I think I've narrowed down the problem to:
"How do we standardize self-describing REST URIs over XHTML?"
This involves two challenges. One is figuring out the proper "Zen"
of REST URI creation, the other is figuring out the best way to
represent API information in XHTML.
Here's a first cut at an answer:
The basic idea is that every URI should support a "?view=api" query
that returns an annotated list of all the calls that can be made
against it -- which by the way is live, so you can do testing at the
same time! The format is the API is the documentation. :-) Note that
you can even specify non-client-supported verbs ("put", "delete")
which would still be well-defined, even if inert.
In addition, every REST result should be similarly encoded in an
appropriate XOXO (or XOXT - table) class, with styling done after the
There's obviously way more that could be done, but its a start.
Importantly, it doesn't try to create a machine-understandable
version of the API; frankly, I don't think any machine is capable of
understanding any meaningful API. Rather, it focuses on enabling
"machine-generated stubs" for invoking the API, and maximizing the
amount of human-readable information.
One could certainly do much more: for example, annotating the
description with <var> and <kdb> and so forth. But, I'll leave that
as another exercise.
Is this making any more sense? Is it worth coming by tomorrow to
discuss over dinner?
-- Ernie P.
Ernest N. Prabhakar, Ph.D. <drernie at opendarwin.org>
Ex-Physicist, Marketing Weenie, and Dilettante Hacker
Probe-Hacker blog: http://www.opendarwin.org/~drernie/
More information about the microformats-discuss