refactor webapi

[zooko]

I would like to change the web API in some of the following ways. I'm not absolutely sure that this is exactly the way to do it, or that there aren't other changes that will suggest themselves as the v0.5 version gets more use.

The following ideas were already posted to the mailing list in this message:

​http://allmydata.org/pipermail/tahoe-dev/2007-August/000101.html

My proposed new webapi is attached as a text file to this ticket.

• The big change: unify discussion of name-based and uri-based commands, and expect the reader to understand both at once, and refactor the document to have six use-case-oriented sections.
• Include a read-write uri (if available) in the metadata instead of by a separate API call.
• Signal mutability by the presence of a RW URI instead of by a separate "mutable" bool.
• add ?overwrite={True,False} for the name-adding commands

See also: a couple of other tickets about changes to webAPI:

#89, #98, #102

[zooko]

webapi-new.txt

[warner]

my proposed changes to the new version

[zooko]

This was done for v0.5.1 release.