tahoe-lafs/trac-2024-07-25

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

New issue

Open

opened 2012-04-11 01:44:25 +00:00 by marlowe · 9 comments

marlowe commented

2012-04-11 01:44:25 +00:00

Owner

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.

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.

tahoe-lafs added the

labels 2012-04-11 01:44:25 +00:00

tahoe-lafs added this to the undecided milestone 2012-04-11 01:44:25 +00:00

davidsarah commented

2012-04-11 02:00:54 +00:00

Author

Owner

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

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

marlowe commented

2012-04-11 02:18:44 +00:00

Author

Owner

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.

Replying to [davidsarah](/tahoe-lafs/trac-2024-07-25/issues/1715#issuecomment-129706): > 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.

tahoe-lafs changed title from ~~/cap and /uri are synonyms~~ to change all docs and generated URLs to point to "/cap" instead of "/uri"

2012-04-11 02:31:56 +00:00

marlowe commented

2012-04-11 02:42:00 +00:00

Author

Owner

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.

marlowe commented

2012-04-11 02:43:13 +00:00

Author

Owner

Attachment ticket-1715.patch (755 bytes) added

**Attachment** ticket-1715.patch (755 bytes) added

ticket-1715.patch

755 B

davidsarah commented

2012-04-11 02:56:26 +00:00

Author

Owner

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.

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 commented

2012-04-11 03:03:41 +00:00

Author

Owner

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.

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 commented

2012-04-11 03:36:33 +00:00

Author

Owner

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?

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 commented

2012-05-17 00:30:20 +00:00

Author

Owner

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

davidsarah commented

2012-11-20 03:02:54 +00:00

Author

Owner

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/".

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/".