[microformats-discuss] Re: XHTML-REST -> APIs

[Dr. Ernie Prabhakar]

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:

http://www.opendarwin.org/~drernie/rest-api.html

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  
fact.

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/