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

[Ryan King]

On Oct 13, 2005, at 8:54 AM, Dr. Ernie Prabhakar wrote:

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

I think there's a good deal that *can* be done towards making the api  
reference machine understandable.

For example, you can apply existing microformats to the form as a  
hint for what kind of data is expected.


> 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?

Definitely. I'd love to talk more about this (and h-plist and XOXT  
and all the other great ideas you've been generating :D)

-ryan

--
Ryan King
ryan at technorati.com