[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:                 |
-------------------------------+-------------------------

Old description:

> I would like to see a section of webapi.rst with a concise table of all
> handled URLs (or prefixes).  For each url, a complete list of possible
> operations initiated by that URL would be extremely useful.
>
> Exhaustive query parameters per operation might make the table too
> cluttered.
>
> The use case is an operations engineer under time pressure without
> specific knowledge of Tahoe-LAFS needs to understand the URL structure in
> order to implement access control, caching, load balancing, or other opsy
> policies.

New description:

 I would like to see a section of webapi.rst with a concise table of all
 handled URLs (or prefixes).  For each url, a complete list of possible
 operations initiated by that URL would be extremely useful.

 Exhaustive query parameters per operation might make the table too
 cluttered.

 The use case is an operations engineer under time pressure without
 specific knowledge of Tahoe-LAFS needs to understand the URL structure in
 order to implement access control, caching, load balancing, or other opsy
 policies.

--

Comment (by davidsarah):

 thedod wrote at #1866:
 > At [source:git/docs/frontends/webapi.rst the WAPI doc] there should be a
 list of of all prefix options, followed by a list of sections describing
 each.
 >
 > {{{/cap}}} appears as an orphan line somewhere on the page, and it's not
 clear from the text whether we should use it and when.
 >
 > {{{/file}}} appears inside the {{{/named}}} section, and theres's also
 no mention of the variant that contains a {{{/@@named=/}}} component (the
 WAPI [actually WUI] links to such urls).
 > What does it mean (removing the component doesn't seem to matter)? Which
 of the 3 options ({{{/named/}}} or {{{/file/}}} with or without
 {{{/@@named=/}}}) is preferred when?
 >
 > Another thing I can't find (maybe it's on some other doc, but then
 webapi.rst should link to it): list (+ explanation) of all cap types:
 {{{DIR2-RO}}}, {{{DIR2-CHK}}}, {{{CHK}}}, etc. (and in general -
 explanation of cap uri syntax).
 > This (or a link to it) should appear before explaining urls that
 *contain* a cap :)

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