[tahoe-lafs-trac-stream] [tahoe-lafs] #1866: Clarify url syntax at WAPI doc

[tahoe-lafs]

#1866: Clarify url syntax at WAPI doc
-------------------------------+-----------------------
     Reporter:  thedod         |      Owner:  marlowe
         Type:  defect         |     Status:  new
     Priority:  normal         |  Milestone:  undecided
    Component:  documentation  |    Version:  n/a
   Resolution:                 |   Keywords:
Launchpad Bug:                 |
-------------------------------+-----------------------

Comment (by 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. :-/

 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/1866#comment:1>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage