REST + microformats as a Bugzilla API

[Myk Melez]

Max Kanat-Alexander wrote:

> 	We have an XML-RPC interface, for 3.0. What we're discussing is whether
> or not we also need a REST interface.
I'd rephrase this a bit to say that we also have a REST interface, and 
what we're discussing is whether to treat it as an interface for clients 
in addition to users.

> 	Usually I like to have some consumer who wants something, before we
> implement it. For example, we have *lots* of people who have wanted the
> XML-RPC interface for a long time, so that gives us a good idea of how
> to implement it, because they'll say "Oh, it really needs to do THIS."
>
> 	It would be interesting to know who our REST clients would be, and we
> could give them what they'd be most interested in.
>   
I agree that we're better off with concrete use cases.  Here's one:

Some engineers at Mozilla (mconnor in particular) use microsummaries to 
keep track of bug counts.  They bookmark bug lists and use a 
microsummary generator to make the label of the bookmark include the 
number of bugs in the list.

The generator updates the bug count periodically by executing a query 
via our REST API (i.e. it requests a URL), downloading the resulting bug 
list, and extracting the bug count from it.

But bug counts are hard to extract from bug lists, because they aren't 
labeled as such.  They are merely inserted as raw text into the HTML 
which comprises a bug list.  They aren't even surrounded by a generic 
element like a DIV or a SPAN to distinguish them from surrounding 
whitespace, and the actual number isn't separated from its "bugs found" 
label.

So instead of extracting a specific node, the generator has to identify 
some other node, travel along a path from that node to the text node 
containing the bug count, and then extract the number from that node.

And since we don't treat the count as data that should be 
programmatically accessible, we're liable to change its location from 
version to version, breaking the existing mechanism for extracting it.

If we treated our REST API as an interface for clients and our HTML as 
structured data, on the other hand, à la microformats, then we might 
surround the bug count with a span identifying it:

<span id="bz_bug_count">41</span> bugs found

And then the generator would be able to extract the number by simply 
referencing the specific node in which it was found.

This doesn't tie our hands against future changes.  We could still move 
this information around in the document.  We could even change the tag 
we use to mark up the number (advising developers to key off the ID only 
and not the tag+ID combination).

All this does is make it possible to extract the information we already 
provide as data, and to do so in a way which is safe against future 
modifications to the HTML in which it is embedded.

-myk