First web interface and service API draft

Hi,

me again after a couple of hours of sleep ;-)

This probably gets a bit longer so if you are not interested in a web service api or the web interface now is your chance to get off the train.

I'm probably making a complete git of myself but that's not uncalled for in this contxt ;-)

For those that are still with me let me start by iterating again that I _do_ care for URIs as the primary API for web service applications _and_ humans. I probably don't have to tell Linux people anything about the importance to get the API right ;-)

As it's fairly early in the web service interface cycle I like to change things around a little bit and starting to get the API straight.

The following considerations should be pretty implementation agnostic and not specific to wit. The interface should be flexible enough to be used as a kind of web command line.

------- /<project>

Ok. The URI should start by stating the project name e.g. /linux-2.6. This does bloat the URI slightly but I don't think that we want to have one root namespace per git archive in the long run. Additionally you can always put rewriting or redirecting rules at the root level for additional convenience when there's an obvious default project.

Should provide some meta data, stats, etc. if available.

------- /<project>/blob/<blob-sha1> /<project>/commit/<commit-sha1>

These are the easy ones: the web interface should be able to spit out
the plain text data of a blob and a commit at these URIs. Users would
be probably scripts and other downloads.
Open questions:
* Blob data should be probably binary ?
* Should it be commit or changeset ? Linus seems to have changed
nomenclature in the REAME
* If we serve the pristine commit objects we will put the email
addresses in plain sight. If we remove or change the email addresses
it's not the original commit object anymore. Thoughts ?

------- /<project>/tree/<tree-sha1>

Tree objects are served in binary form. Primary audience are scripts, etc. Human beings will probably get a heart attack when they accidentally visit this URI.

------- /<project>/blob/<blob-sha1>.html /<project>/commit/<commit-sha1>.html /<project>/tree/<tree-sha1>.html

A HTML version of blob, commit and tree fully linked aimed at human beings.

------- /<project>/tree/<tree-sha1>.tar.bz2 /<project>/tree/<tree-sha1>.tar.gz /<project>/commit/<commit-sha1>.tar.bz2 /<project>/commit/<commit-sha1>.tar.gz

Tarballs of the specified commits or trees. Note that these can be individual subtrees too.

------- /<project>/tree/<tree-sha1>/diff/<ancestor-tree-sha1>

Unified plain text recursive diff of the given trees. I guess the
user could specify any two tree ids but the relevance of the results
would vary greatly ;-)
* Possibly a DOS issue
* does something like /<project>/tree/<tree-sha1>/diff/ make sense
producing a full diff from scratch ?  

------- /<project>/tree/<tree-sha1>/diff/<ancestor-tree-sha1>/html

Non recursive HTML view of the objects which are contained in the diff fully linked with the individual HTML views.

------- /<project>/blob/<blob-sha1>/diff/<ancestor-sha1>

Unified plain text diff of the given blobs.
* again /<project>/blob/<blob-sha1>/diff/ sensible ?

------- /<project>/blob/<blob-sha1>/diff/<ancestor-sha1>/html

HTML view (probably colorized) view of a single blob diff.

------- /<project>/changelog/<time-spec>

HTML changelog for the given <time-spec>. I think valid values for timespec should be number of days <nnn>d, number of entries <nnn> and the keyword 'all'.

* perhaps additionally number of hours <nnn>h, number of months
  <nnn>m, number of years <nnn>y. Combinations shouldn't be allowed
* time ranges are probably overkill
* is a plain text version needed /<project>/changelog/<time-spec/plain?

------- /<project>/changelog/<time-spec>/search/<regexp>

HTML changelog for the given <time-spec> filtered by the <regexp>.

* again plain version needed ?

------ /<project>/changelog/<time-spec>/search/author/<regexp> /<project>/changelog/<time-spec>/search/committer/<regexp> /<project>/changelog/<time-spec>/search/signedoffby/<regexp>

convenience wrappers for generic search restricted to these fields.

------

open questions:
* how to generate and publish additional merge information ?
* how to generate and publish tree and blob history information ? This
is probably expensive with git.
* how to represent branches ? should we code up the branches in the
project id like linux-2.6-mm or whatever ?

Comments ? Ideas ? Other feedback ?

				Christian