[tahoe-lafs-trac-stream] [tahoe-lafs] #1663: Add a concise table of the URL tree to webapi.rst.

[tahoe-lafs]

#1663: Add a concise table of the URL tree to webapi.rst.
-------------------------------+-------------------------
     Reporter:  nejucomo       |      Owner:  marlowe
         Type:  enhancement    |     Status:  assigned
     Priority:  normal         |  Milestone:  undecided
    Component:  documentation  |    Version:  1.9.0
   Resolution:                 |   Keywords:  webapi docs
Launchpad Bug:                 |
-------------------------------+-------------------------

Comment (by davidsarah):

 zooko wrote at #1866:

 Replying to [comment:1 zooko]:
 > Okay, to close this ticket, update webapi.rst to answer all these
 questions. Here are some answers you could use to that end...
 >
 > {{{/cap}}} was a plan that I had to rename "uri" to "cap" everywhere. I
 thought it was more helpful to users to call those things caps instead of
 uris.
 >
 > Part of why Brian had agreed to go along with this was that Kevin Reid
 emphasized to us that we're not supposed to call a thing a "uri" unless it
 has some sort of official recognition from some namespace allocator like
 IANA or something.
 >
 > We wound up changing most but not all of the things that were easy to
 change -- the docs and some of the source code -- but not changing how it
 is spelled in the WAPI.
 >
 > I guess we should consider resuming that process of renaming, if only
 because a half-renamed thing is almost as bad as a consistently bad badly-
 named thing. :-/

 +1 (a half-renamed thing is worse, IMHO)

 > Anyway, {{{/cap}}} *ought* to be a synonym of {{{/uri}}}, but I'm not
 sure what happens if you actually use it.
 >
 > The {{{/@@named=/}}} feature is kind of complicated. The goal is: tell
 the web server (tahoe-lafs gateway) that the resource you want to download
 is a certain cap, e.g.
 "URI:CHK:egrocatgmbuoqra3e3jptkzvwe:543sre2wsjmqwbk73in76oqaemi35iqeyzggavc4vp6kkvc43nkq:1:1:948821",
 but at the same time tell the web *browser* that the resource you are
 fetching is named something like
 "Murphy-2012-Deaths!__Preliminary_Data_For_2010.pdf". The way we do this
 is by appending a string after the cap which will be ignored by the server
 (LAFS gateway), but which will make the browser think that the file has
 that name. So, for example
 {{{/uri/URI:CHK:egrocatgmbuoqra3e3jptkzvwe:543sre2wsjmqwbk73in76oqaemi35iqeyzggavc4vp6kkvc43nkq:1:1:948821/@@named=/Murphy-2012-Deaths__Preliminary_Data_For_2010.pdf}}}.
 >
 > Now, the further complication is that if the cap is a dir cap as opposed
 to a file cap, then {{{/uri/URI:DIR2-MDMF-
 RO:ppnrefnrnovjpoiv3jirjnpoim:obhqprvm6hafvarzzssrawgazx6p6tgopi4fslirhelg7xqyfr6a/@@named=/foo}}}
 could be interpreted by the web server (LAFS gateway) as meaning "Get the
 child out of the dir whose name is {{{@@named=}}} and then treat that
 child as a directory and look in that for a child of it named {{{foo}}}.
 In order to avoid that misinterpretation, we added the {{{/file/}}}
 instead of {{{/uri/}}} to specify that this is not a dir.
 >
 > Here was a thread about this on tahoe-dev long ago:
 >
 > https://tahoe-lafs.org/pipermail/tahoe-dev/2008-May/000573.html
 >
 > Frankly, the resulting API is kind of weird and I wonder if we couldn't
 come up with a simpler and better one!
 >
 >
 > Now as to the list of cap types and cap syntax, there are at least the
 following two docs, and they should be cross-linked, and linked to from
 webapi.rst, and probably unified:
 >
 > * wiki:Capabilities
 > * [source:git/docs/specifications/uri.rst]

-- 
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1663#comment:15>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage