REST + microformats as a Bugzilla API
myk at mozilla.org
Tue Oct 17 21:30:43 UTC 2006
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"
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.
More information about the developers