change all docs and generated URLs to point to "/cap" instead of "/uri"

[marlowe]

From #tahoe-lafs:

13:58 < warner> I also noticed that /uri and /cap are synonyms.. not sure if that's documented

13:59 < zooko> I had the idea, many years ago, to rename "uri" to "cap" everywhere, but never finished that process...

14:00 < marlowe> warner: if you create the ticket, and assign it to docs, I will make the change

14:00 < warner> I think that synonym came from that process

14:00 * zooko nods

14:01 < marlowe> also, once I finish #1663 we should have a good idea on what is a synonym for what

14:01 < zooko> I had planned to change the Web API docs to direct programmers to the new name -- /cap/ -- and leave the old one for backward-compatibility.

[davidsarah]

Another option would be to delete /cap. Why have two ways to do things?

[marlowe]

Replying to davidsarah:

Another option would be to delete /cap. Why have two ways to do things?

You read my mind. I think ticket #1663 will help us get an idea where we have synonyms and then create tickets to either remove the cruft or maintain backwards compatibility. I added Brian and Zooko to the ticket as they can shed more light on it than I.

In the meantime until we decide how to proceed on the above, I will make the necessary changes to webapi.rst.

[marlowe]

The attached patch is a workaround, until we get all instances of /uri changed to /cap, we need to have this in webapi.rst. If someone can tell me when /cap was introduced, I will add the version information into webapi.rst. I submitted a pull request to github with this patch.

[davidsarah]

Reasons not to rename /uri to /cap:

• it's unnecessary work;
• /cap is not that much better a name;
• in order not to be disruptive to older third-party tools, or Tahoe CLI instances, connecting to a newer gateway, we'd have to maintain /uri as well as /cap;
• there's no evidence that anyone is using /cap, and it wasn't documented, so there's no reason not to just delete it.

[davidsarah]

Incidentally, if we are going to change the gateway URLs, I'd rather shorten them by not having any additional prefix, since the URI: prefix (or lafs: if we change it to that) is unambiguous. This would only involve a slight complication in the root handler.

[zooko]

David-Sarah: I think "cap" is a much better name. These things are not officially URIs, as they aren't officially recognized by IANA and they don't even follow the URI spec. Also, they are not even conceptually URIs, because an "identifier" does not, according to most people's conceptions, convey authority. That's how a cap differs from an identifier.

Also, we use the name cap fairly consistently in all the documentation except for the URL structure itself, so currently someone who reads the docs has to remember "Okay, '/uri/' is where the cap goes.", which seems harder than "Okay, '/cap/' is where the cap goes.".

I like your idea of removing the "/uri/" or "/cap/" altogether. That's intriguing. Want to talk about that?

[davidsarah]

Accepting to remind me to talk about removing "/uri/" or "/cap/"

[davidsarah]

So, we can get away with removing "/uri/" or "/cap/" because the URI: prefix (or lafs: if and when we switch to that) makes the meaning unambiguous. The root handler can just check whether the immediate child name starts with "URI:", and if it does, delegate to the same handler as "/uri/".